REST API

Base URL

https://api.graphsignal.com

Authentication

API key in request header:

X-API-KEY: <your-api-key>

Common error responses:

• 401 Unauthorized: Invalid or missing credentials.
• 422 Unprocessable Entity: Missing or invalid query parameters.

GET /api/v1/context/signals/

Query signal context (profiles, errors, traces, metrics) for a time range and tags. Returns {"context": {...}} with top-level keys meta, resources, profile, errors, traces, and metrics.

Query parameters:

• start_time_ns (required, integer): Start of time range in Unix nanoseconds.
• end_time_ns (required, integer): End of time range in Unix nanoseconds.
• tags (optional, string): Filter by tags using semicolon-separated key:value pairs (example: env:prod;service:inference).

Example request:

curl -G "https://api.graphsignal.com/api/v1/context/signals/" \
  -H "X-API-KEY: $GRAPHSIGNAL_API_KEY" \
  --data-urlencode "start_time_ns=1773100800000000000" \
  --data-urlencode "end_time_ns=1773273600000000000" \
  --data-urlencode "tags=env:prod;service:inference"

For a full description of the context payload and how to interpret each section, call GET /api/v1/context/guide/ or run graphsignal-context guide.

GET /api/v1/context/summary/

Query a pre-computed, scalar-only signal summary (performance analysis) for a time range and tags: engine info and metrics, host metrics, traffic and latency stats, GPU time by kernel class, GPU memory usage, prefill/decode phases, bottleneck findings, anomalies, and grouped errors. Returns {"summary": {...}}. Use this as a lightweight overview before fetching full context from /api/v1/context/signals/.

The summary describes a single engine run: the tags parameter must include the run.uid tag, otherwise the endpoint returns 400 Bad Request. run.uid is set automatically by the profiler per engine process launch; find values in available_tags of a /api/v1/context/signals/ response. The companion workload_command_hash tag is shared by all runs of the same workload command — use it to find previous runs of the same configuration.

Query parameters:

• start_time_ns (required, integer): Start of time range in Unix nanoseconds.
• end_time_ns (required, integer): End of time range in Unix nanoseconds.
• tags (optional, string): Filter by tags using semicolon-separated key:value pairs. Must include the run.uid tag (example: run.uid:1a2b3c4d5e6f).

For a CLI wrapper, run graphsignal-context summary.

GET /api/v1/context/guide/

Returns the signal guide — documentation for interpreting the context JSON returned by /api/v1/context/signals/.

Example request:

curl "https://api.graphsignal.com/api/v1/context/guide/" \
  -H "X-API-KEY: $GRAPHSIGNAL_API_KEY"

Response:

200 OK with text/plain body containing the guide content.