Request traces

The request log records what your applications sent through INFRO: the model, selected provider connection, outcome, timings, usage and estimated provider cost. It is operational evidence; it is not an invoice for model usage.

List and retrieve requests

curl "https://api.infro.io/v1/requests?limit=25&status=error" \
  -H "Authorization: Bearer $INFRO_API_KEY"

Use GET /v1/requests/{id} for a request detail. limit sets the page size, from 1 to 100 (default 20). List responses include data, has_more and next_cursor. Pass that cursor as after to fetch the next page, keeping the same filters and sort. sort is newest (the default), slowest (latency, highest first) or costliest (estimated provider cost, highest first; unpriced requests come last, never as $0). Every list also says what it searched: window_start (the oldest instant read), window_end (your to, or null for now), retention_days, and requested_from when your plan's window moved the from you sent.

Which keys can read history

A gateway key that can call models cannot automatically read every application's history. Each key carries its own history access, set when it is created or edited in the console:

Environment is matched against the environment recorded when each request ran, not the key's current environment. Requests recorded before this was stored have no environment and are visible only to keys without an environment filter. Query filters narrow what a key can read; they never widen it. A request outside a key's scope answers exactly like an ID that does not exist.

Captured prompt and response bodies (content) need separate payload access on the key, granted by an owner or admin. Content is never returned after its retention deadline, even if deletion has not run yet, and shortening the retention setting applies to content already captured.

History is measured back from now, whatever to you send. An organization without an active or trialing subscription reads no more than the smallest plan's window.

Every filter is an exact match on a value, and each is answered from the whole retained window, not from one page. There is no free-text search over request content. A filter naming something that does not exist in your organization (an unknown route slug, another organization's trace ID) returns an empty list, never an unfiltered one.

Response cache on a request

GET /v1/requests and its export accept cache=hit|miss|bypass|uncacheable|disabled. Each request object carries cache: null when the request never reached the cache step, otherwise {status, source_request_id, reason, provider_billed, estimated_provider_cost_avoided}. reason explains an uncacheable request, or a miss whose lookup failed (lookup_error, lookup_timeout). estimated_provider_cost_avoided is a USD number on hits only, null when the source request was unpriced. See Response cache.

Find a request in the console

The search box on Requests takes an identifier and searches the whole retained window:

Each search becomes a removable filter chip and is written to the page address, so a narrowed view can be shared as a link.

Export requests as CSV

curl -o requests.csv "https://api.infro.io/v1/requests/export?trace_id=run_42" \
  -H "Authorization: Bearer $INFRO_API_KEY"

GET /v1/requests/export takes the same filters as GET /v1/requests and returns exactly the rows that list would return, in the same sort order (newest first by default), as one CSV file. It needs the same history access as the list, and a scoped key exports only its own scope. The console's Export CSV button on Requests downloads the current filters and period.

• Up to 50,000 requests per file. A larger result is refused before any data is sent, with 400 and code export_too_large: narrow the window or add a filter. A file is never cut short silently. dry_run=true returns the row count and the window as JSON without producing a file.
• Content is never exported. Prompts, responses and captured payloads are not in the file, even when payload logging is on and the key may read content.
• estimated_provider_cost_usd is an estimate of what your provider will bill you, not an INFRO charge. It is empty for an unpriced request, never 0, and price_source is empty with it. A request refused before anything ran is a known 0.
• When you send no to, the window ends at the moment the export starts, so requests served while the file streams are not included.
• Every export is recorded in your organization's audit log (who, the filters, the row count) and exports are rate limited per organization.

The column contract is versioned by the X-INFRO-Export-Schema-Version response header (currently 1); new columns are only ever added at the end. Headers also carry X-INFRO-Export-Rows, X-INFRO-Window-Start, X-INFRO-Window-End and X-INFRO-Retention-Days. Every field is quoted, lines end in CRLF, and the file has no byte-order mark. A text value that would start a spreadsheet formula (=, +, -, @, tab, carriage return) is prefixed with '; numbers are left as numbers. If Excel shows accented characters wrongly, open the file with Data → From Text/CSV and choose UTF-8.

Two columns are added at the end, after tags: cache_status and cache_source_request_id. The schema version stays 1, because columns are only ever added at the end.

Group requests into a run

A retrieval-augmented answer or an agent turn is several model calls. Attach three reserved keys to metadata and INFRO records them as indexed columns, so you can ask what one run of a workflow cost rather than what one request cost.

A malformed reserved key is refused with 400 and code invalid_attribution naming the key, rather than being dropped. Attribution that fails quietly is discovered weeks later as a hole in a cost report; a refusal is discovered on the first request of an integration. Every other metadata key stays free-form.

Requests that cannot carry a JSON body — multipart audio, for example — can send X-INFRO-Trace-Id, X-INFRO-Workflow, X-INFRO-Step, X-INFRO-Feature and X-INFRO-User-Id (for user_id) instead. A W3C traceparent supplies the trace ID when nothing else does, and always nests INFRO's OpenTelemetry spans inside your own trace. Precedence is body metadata, then headers, then traceparent.

GET /v1/traces/{trace_id} returns every request in one run in order, with cost by step and by modality. The total covers model calls made through INFRO and nothing else: your vector database, your retrieval and your own compute are not included. It is a lower bound whenever any successful call in the run is unpriced, and cost_is_partial says so rather than the figure being filled in.

GET /v1/usage?group_by=workflow — also step, feature, user and tag:<key> for a promoted tag — reports the same figures aggregated. These are the groupings whose cardinality you choose, so they return the hundred largest by estimated cost plus one __other__ row holding the remainder, with groups_truncated set. The rows still add up. Requests that carried no value are one group: null row, never folded into __other__, so you can see how much traffic is unattributed. Attribution is recorded from the request that first carries it; it is not applied retroactively. trace_id is not a grouping: a row per run is what GET /v1/traces/{trace_id} and Unit economics are for.

Tool calls in a trace

Tool calls made through the MCP gateway with the same trace id are returned by GET /v1/traces/{trace_id} beside the model requests, under the same key scope, history window and cap. The response gains tool_calls (in time order: id, created_at, server_id, server_slug, server_name, tool, outcome, error_code, latency_ms, step, workflow; metadata only), tool_call_count, tool_calls_truncated and covers_tool_calls: true. Every existing field keeps its meaning: requests, totals and the estimated cost cover model calls only, and covers is unchanged. outcome is ok, tool_error, refused, upstream_error, timeout or cancelled. A trace that has only tool calls is still found; its start, end and duration then come from the tool calls.

{
  "trace_id": "run-7f3a",
  "requests": [ ... ],
  "tool_calls": [
    {
      "id": "gtc_01JA2Q8R5W",
      "created_at": "2026-10-07T09:14:03.512Z",
      "server_id": "mcps_01JA1V0K7M",
      "server_slug": "github",
      "server_name": "GitHub",
      "tool": "github_list_issues",
      "outcome": "ok",
      "error_code": null,
      "latency_ms": 412,
      "step": "triage",
      "workflow": "issue-triage"
    }
  ],
  "tool_call_count": 1,
  "tool_calls_truncated": false,
  "covers": "model_calls_through_infro",
  "covers_tool_calls": true
}

Read a request record

• Provider and connection details identify your own account that served the request. Fallback attempts record their models, route positions, errors and timings.
• usage.cost is an estimated provider cost in USD, with a price source when priced. An unpriced model is not a free model. Your provider invoice is authoritative.
• cost_breakdown itemizes the estimate when available. It can be null when a record was not priced or predates itemization.
• Optional content is available only when capture was allowed and the payload has not expired. Customer-supplied metadata may itself contain personal data.
• guardrails is {action, findings} when your organization's guardrails acted on the request, and null otherwise. action is blocked_input, blocked_output, redacted or flagged; each finding is {detector, stage, action, count}. The matched text is never stored, so the record holds counts only.

History and export

Developer includes 7 days of queryable history, Startup 14, Team 30, Business 90 and Enterprise 365. The API reports the applied window. Optional payload logging is a separate opt-in with plan limits; see Privacy.

Use the request API or the CSV export above to keep your own history, or configure OpenTelemetry on an eligible plan. There are no scheduled or emailed exports. See Exports and OpenTelemetry.