Diagnostics

Safe, read-only diagnostics for The Grid CLI and for raw HTTP clients using Platform, Trading, or Consumption authentication.

Diagnostics are safe by default. The endpoints below only read account, key, model, market, and readiness state. They do not place orders, reserve inference tokens, create keys, switch account mode, or trigger billable inference.

Use diagnostics when onboarding an integration, debugging 401/403 responses, checking clock skew, or confirming which auth path is configured.

Fastest path: Grid CLI

The public Grid CLI can run local checks and all configured remote diagnostics:

grid diagnostics

Useful variants:

grid diagnostics --local-only
grid diagnostics --surface platform
grid diagnostics --surface trading
grid diagnostics --surface consumption
grid diagnostics --json

The command reports local URL/credential configuration first, then calls each read-only diagnostics endpoint for the credentials it can find.

Response shape

Every diagnostics endpoint returns a checklist-style envelope:

{
  "data": {
    "status": "ok",
    "service": "trading",
    "server_time": "2026-07-02T14:43:40Z",
    "checks": [
      {
        "name": "authentication",
        "status": "ok",
        "code": "signed_request_authenticated",
        "detail": "Signed request authenticated for [e-mail].",
        "next_action": "Use this same signing key for other Trading API reads and order operations."
      }
    ],
    "summary": {}
  }
}

status is ok, warn, or fail. A warn means the endpoint was reachable and authenticated, but something about setup may block the workflow you expected.

Platform diagnostics

Use Platform diagnostics to verify OAuth/session authentication, email/legal readiness, account status, account mode, and whether active Consumption and Trading keys exist.

curl -sS "https://platform.api.thegrid.ai/v1/diagnostics" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

Common warnings:

• platform_oauth_missing: the CLI cannot run Platform diagnostics until you run grid auth login.
• email_unverified: verify the account email before production automation.
• legal_terms_not_accepted: accept current legal terms in the dashboard.
• no_api_keys_present: create a Consumption key or Trading signing key for the surface you plan to use.

Consumption diagnostics

Use Consumption diagnostics to verify a Consumption API key without making an inference request.

OpenAI-compatible header:

curl -sS "https://api.thegrid.ai/v1/diagnostics" \
  -H "Authorization: Bearer $CONSUMPTION_KEY"

Anthropic-compatible header:

curl -sS "https://api.thegrid.ai/v1/diagnostics" \
  -H "x-api-key: $CONSUMPTION_KEY"

This endpoint reports whether the key authenticated, account status, visible model catalog count, and whether the account is in Auto Mode or Advanced Mode. It does not route to a supplier and does not return a 307.

Consumption auth failures include machine-readable error codes:

{
  "errors": {
    "code": "invalid_api_key",
    "detail": "Invalid or expired API key",
    "server_time": "2026-07-02T14:43:40Z"
  }
}

Trading diagnostics

Use Trading diagnostics to verify Ed25519 signing, account mode, account status, visible trading accounts, routable markets, and order-control readiness.

What the signature covers

Every signed Trading request (including diagnostics) uses the same payload:

{timestamp}{HTTP_METHOD}{request_path}{raw_body}

Part	Included in signature?	Notes
Unix timestamp	Yes	Must be within 30 seconds of server time
HTTP method (GET, POST, …)	Yes	Uppercase
Request path (e.g. /v1/orders)	Yes	Pathname only — no query string
Query parameters (?status=open&limit=3)	No	Sent on the wire but parsed after verification
Request body (JSON on POST/PUT/PATCH)	Yes	Empty string for bodyless GET / DELETE

This applies to all methods, not just GET. For example, POST /v1/orders signs /v1/orders plus the JSON body; any query string on the URL is still excluded.

List endpoints often take filters in the query string. Sign only the pathname:

• Request: GET /v1/orders?status=filled&limit=10
• Sign: GET + /v1/orders + `` (empty body)
• Do not sign /v1/orders?status=filled&limit=10

For diagnostics specifically, the signed path is /v1/diagnostics and the body is empty.

curl -sS "https://trading.api.thegrid.ai/v1/diagnostics" \
  -H "x-thegrid-timestamp: $TIMESTAMP" \
  -H "x-thegrid-fingerprint: $FINGERPRINT" \
  -H "x-thegrid-signature: $SIGNATURE"

Python signing example:

import base64
import os
import time
import requests
from nacl.signing import SigningKey

private_key = base64.b64decode(os.environ["GRID_TRADING_PRIVATE_KEY"])
fingerprint = os.environ["GRID_TRADING_FINGERPRINT"]
timestamp = str(int(time.time()))
method = "GET"
path = "/v1/diagnostics"
body = ""

signing_key = SigningKey(private_key[:32])
signature = signing_key.sign(f"{timestamp}{method}{path}{body}".encode()).signature

response = requests.get(
    "https://trading.api.thegrid.ai/v1/diagnostics",
    headers={
        "x-thegrid-timestamp": timestamp,
        "x-thegrid-fingerprint": fingerprint,
        "x-thegrid-signature": base64.b64encode(signature).decode(),
    },
    timeout=10,
)
print(response.status_code)
print(response.json())

If timestamp drift is the problem, Trading auth errors include the server time and observed drift:

{
  "errors": {
    "code": "timestamp_out_of_range",
    "detail": "Timestamp is too far from current time",
    "server_time": "2026-07-02T14:43:40.123456Z",
    "context": {
      "max_drift_seconds": 30,
      "observed_drift_seconds": 60,
      "request_timestamp": 1783003360,
      "server_timestamp": 1783003420
    }
  }
}

Which endpoint should I call?

• Call Platform diagnostics when OAuth login, account setup, or key creation is confusing.
• Call Consumption diagnostics when an inference key fails before any model request should be sent.
• Call Trading diagnostics when signed Trading API calls fail, account mode is unclear, or order placement is blocked.
• Run grid diagnostics when using the CLI; it combines local configuration and remote endpoint checks in one report.