Skip to main content
The Observability API reads a project’s log entries, metric series, traces, and alerts. It also publishes the catalog of API error types. Each signal answers a different question about the same application.

​
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

Suppose a support agent gives an incomplete answer after calling an external service. Its run events show the attempted work, a related trace can locate a failure or delay, and log entries can supply the emitted error. 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. These findings can inform an implementation change and a new evaluation case. The Evaluations API provides the definitions and reports for assessing that change; creating a regression case is part of your development process.

​
Get started

Inspect logs and traces shows the requests and verification steps for investigating an execution.

​
API references