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
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, andtodefaults to now. At most 31 days apart, and never earlier than your plan's request history;window_startsays where the search began. sortstringnewest(default, by start time),costliest(estimated provider cost),slowest(duration) orerrors(failed requests). Highest first.min_coststring- Only runs whose estimated provider cost is at least this many US dollars, for example
0.25. has_errorsbooleantrue: 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 andsort; a page never skips or repeats a run while new requests arrive. every request filterquerymodel,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-5lists the runs that called that model, with their figures over the requests that match.
Response
{
"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,
costis a lower bound andcost_is_partialistrue, with the count inunpriced_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;
nullotherwise. scoreobject- The run's scores:
count,meanof the numeric ones (nullwhen there are none), andthumbs_up/thumbs_downfor true/false scores. prompt_versionsarray- Each managed prompt version the run's requests were served from:
id,slug(nullif the prompt can no longer be found) andversion. 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.