Observability API

The Observability API reads project logs, metrics, traces, and alerts. It also publishes the API error catalog.

Log entries

A log entry is one message from the project's runtime, the API, or the proxy. Filter by level, service, time window, search text, or a trace, request, or run ID. Reading log entries requires project.logs.read.

A page has data, page_info, and stats. Newest entries come first unless you set sort_order to asc. Pass page_info.next as cursor to read the next page, and send the same filters with it. A cursor keeps the original time window, so don't send start or end with it.

A page can hold fewer entries than limit, or none, and still have page_info.next. Keep reading until page_info.next is null.

Log entries are kept for 31 days. One request spans at most 30 days.

Metric series

A metric series is one time series of a project metric: a metric name, a label set, and timestamped points. A query takes a metric name and supported label filters, not PromQL. Reading metrics requires project.metrics.read, which API keys get from the metrics:read scope.

Metrics are kept for 395 days. One request spans at most 31 days. step accepts 10s to 1d and defaults to 60s.

A metric result is never partial:

  • Too many points: A time window and step that need more than 11,000 points per series return invalid-input (400) before the query runs. For a 31-day window, a step of 5m is safe: it gives 8,929 points.
  • Too large a result: More than 100 series, or a response over 8 MiB, returns payload-too-large (413). Add a label filter, choose an aggregation, use a larger step, or shorten the window.

Alerts

An alert is one firing episode of a Veryfront alert rule for a project. Its status is firing or resolved. Alerts cover the last 30 days, newest first. Each alert links to the log entries and traces of its time window while that data is retained. Reading alerts requires project.logs.read.

Error types

An error type is one entry of the public API error catalog, identified by its slug. The type URI of every API error response resolves to its error type. The list is sorted by slug and isn't paginated. Categories are uppercase, such as AUTH or VALIDATION.

The REST and GraphQL catalog needs no credential. The MCP tools need an authenticated MCP connection.

Rate limits

Each project can run 30 log queries and 30 metric queries a minute. The next request returns rate-limit-exceeded (429). Wait before you retry.

Traces and spans

A trace connects related operations across an execution. Spans describe parts of that work, including timing and error status.

Trace summaries and details can return a bounded selection of spans. The span-list operation provides pagination and error filtering when you need to investigate further.

Runs and analytics

Execution API run events preserve execution progress and output. A trace adds diagnostic context. It does not replace the run record.

Account analytics summarize conversation and run activity, including counts, outcomes, duration, and supported usage breakdowns. Spending and credit balances belong to the Billing and Usage API.

From a failure to a change

If an agent gives an incomplete answer after an external service call, inspect its run events. Follow the related trace to locate failures or delays, then read the logs for error details.

Use shared request, trace, or run IDs where available. Nearby timestamps alone do not establish that records describe the same work, and permissions still apply to each resource.

Use the findings to change the implementation and add an evaluation case. The Evaluations API provides definitions and reports for assessing the change.

Get started

Inspect logs and traces to investigate an execution.

API references