> For the complete documentation index, see [llms.txt](https://thegrid.ai/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://thegrid.ai/docs/api-reference/diagnostics.md). # Diagnostics 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: ```bash grid diagnostics ``` Useful variants: ```bash 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: ```json { "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 trader@example.com.", "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. ```bash 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: ```bash curl -sS "https://api.thegrid.ai/v1/diagnostics" \ -H "Authorization: Bearer $CONSUMPTION_KEY" ``` Anthropic-compatible header: ```bash 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: ```json { "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. ```bash 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: ```python 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: ```json { "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. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://thegrid.ai/docs/api-reference/diagnostics.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.