Skip to content

DocsObservability

Runs

List runs, the requests that share a trace id, with duration, errors, models, estimated provider cost, scores and prompt versions, filtered and sorted.


A run is the requests of one workflow that carried the same trace_id: an agent turn, a retrieval-augmented answer, a document pipeline. Send metadata.trace_id (or X-INFRO-Trace-Id) and metadata.workflow on each call, as Request traces describes, and GET /v1/runs lists one row per run, so you can find the expensive, slow or failing ones without reading every request. Runs are grouped by workflow and trace id together, because trace ids are yours and two workflows can reuse one. A request with no trace_id belongs to no run.

List runs

Costliest failing runs of one workflow, last 24 hours
curl "https://api.infro.io/v1/runs?workflow=support-answer&sort=costliest&has_errors=true" \
  -H "Authorization: Bearer $INFRO_API_KEY"

The key needs history access, as GET /v1/requests does: a scoped key sees the runs of its own project (or its own requests), an organization key every run. Each figure covers only the requests the key may read.

from, toISO 8601
The window. Default: the 24 hours before to, and to defaults to now. At most 31 days apart, and never earlier than your plan's request history; window_start says where the search began.
sortstring
newest (default, by start time), costliest (estimated provider cost), slowest (duration) or errors (failed requests). Highest first.
min_coststring
Only runs whose estimated provider cost is at least this many US dollars, for example 0.25.
has_errorsboolean
true: runs with at least one request that ended with a status of 400 or above. false: runs with none.
score_belownumber
Only runs whose mean numeric score is below this value. Runs with no numeric score are left out.
limitinteger
Runs per page, 1 to 100. Default 25.
afterstring
The previous page's next_cursor, unchanged. Keep the same filters and sort; a page never skips or repeats a run while new requests arrive.
every request filterquery
model, project, key, provider, connection, route, endpoint, modality, surface, status, trace_id, workflow, step, feature, user_id, session_id, tag.<name> and the rest of the request log's filters choose which requests are grouped, before grouping. model=openai/gpt-5 lists the runs that called that model, with their figures over the requests that match.

Response

json
{
  "object": "list",
  "data": [
    {
      "object": "run",
      "trace_id": "run_42",
      "workflow": "support-answer",
      "started_at": "2026-11-16T09:14:02.120Z",
      "ended_at": "2026-11-16T09:14:09.884Z",
      "duration_ms": 7764,
      "requests": 4,
      "errors": 1,
      "cost": 0.01832,
      "cost_is_partial": false,
      "unpriced_requests": 0,
      "models": ["anthropic/claude-sonnet-5", "openai/text-embedding-3-small"],
      "user_id": "cus_8812",
      "session_id": null,
      "score": { "count": 2, "mean": 0.8, "thumbs_up": 1, "thumbs_down": 0 },
      "prompt_versions": [{ "id": "prm_01JD…", "slug": "support-reply", "version": 3 }]
    }
  ],
  "has_more": true,
  "next_cursor": "eyJ2Ijoi…",
  "window_start": "2026-11-15T09:20:00.000Z",
  "window_end": "2026-11-16T09:20:00.000Z",
  "retention_days": 30,
  "sort": "costliest",
  "covers": "model_calls_through_infro"
}
duration_msinteger
From the first request's start to the end of the last one to finish.
requests, errorsinteger
Requests in the run, and how many ended with a status of 400 or above.
costnumber
The sum of INFRO's estimates of what your providers bill for the run's model calls, in USD. INFRO adds nothing to it. When a successful request in the run was unpriced, cost is a lower bound and cost_is_partial is true, with the count in unpriced_requests; nothing is filled in.
modelsarray
Every model the run's requests named, sorted.
user_id, session_idstring | null
Set when every request of the run that carries one carries the same value; null otherwise.
scoreobject
The run's scores: count, mean of the numeric ones (null when there are none), and thumbs_up / thumbs_down for true/false scores.
prompt_versionsarray
Each managed prompt version the run's requests were served from: id, slug (null if the prompt can no longer be found) and version.
coversstring
Always model_calls_through_infro: your vector database, retrieval and own compute are not in any figure.

For one run's requests in order, with cost by step, call GET /v1/traces/{trace_id}. The console lists the same runs, and opens a run's steps from a row.

Through the management API and MCP

GET /manage/v1/runs takes the same parameters with a management token holding analytics:read, and never returns request content. The INFRO MCP server's list_runs tool reads the same list for an assistant, and search_requests takes workflow and step filters.

↑ ↓ navigate↵ open/ anywhere in docs