Skip to content
Docs menu

Log queries over the admin API

Run, page, facet and save request-log queries from scripts through /api/admin/v1/logs; the query language itself is on the console's log query page.

View .md

The console's request explorer, live feed, alerts and exports all take the same one-line query. It searches your org's request log (metadata such as model, key, status, latency and cost, and, if your org keeps content, the stored prompts and responses), filters it, and can turn it into a table or a chart. This page is the query API; the language reference is Log query language; the logs routes themselves are listed on the admin API's logs page.

Examples

Query Finds
timeout any request whose id, model, key, daemon, provider, error, session or route mentions timeout
"rate limit exceeded" an exact phrase
model:gpt-5.5 status:5xx server errors on one model (asked for or served)
model:gpt-* -model:gpt-4* a wildcard, minus another
model:(gpt-5.5 OR glm-5.3) latency:>2s either model, slower than 2 seconds
status:429 since:15m rate limited in the last 15 minutes
key:laptop OR key:ci-* one key or a family of keys
daemon:gpu-box ttft:<300ms fast first tokens on one daemon
served:cloud provider:openai cost:>$0.05 expensive requests the cloud sent to OpenAI
tokens:>10k is:error big requests that failed
error:rate_limited last:24h one error code over the last day
since:2026-10-01 until:2026-10-02 one whole day, in the query's time zone
@yesterday | count by model yesterday's requests per model
status:error | count by error | sort count desc | limit 10 the ten commonest errors
| p95(latency), p50(ttft) by provider latency percentiles per provider
| top 5 model by sum(cost) the five costliest models
| timeseries 5m count by status requests per status in 5-minute buckets
prompt:"refund policy" requests whose stored prompt says that (needs content:read)
tool:web_search has:image requests that called a tool and sent an image
gear:review project:billing @thisweek one gear's spend on one project this week

Run one over the admin API:

curl -s -G "https://cloud.usevenom.dev/api/admin/v1/logs/query" \
  -H "Authorization: Bearer $VENOM_ADMIN" \
  --data-urlencode 'q=status:5xx | count by model' \
  --data-urlencode 'tz=Europe/Berlin'
const url = new URL("https://cloud.usevenom.dev/api/admin/v1/logs/query");
url.searchParams.set("q", "latency:>5s | sort latency desc | limit 20");
const res = await fetch(url, { headers: { Authorization: `Bearer ${process.env.VENOM_ADMIN}` } });
const body = await res.json();
if (body.result.kind === "rows") for (const r of body.result.rows) console.log(r.id, r.model, r.latency);

The admin API takes the credentials described in the overview. Every logs route needs logs:read.

The query language

The language is the same everywhere it is used, so it has one reference, on the console's page: grammar, fields, values, the time window (here the zone is the tz parameter, an IANA name, default UTC), pipes and their limits and diagnostics. The examples above cover the common shapes.

Content search

prompt:, response: and content: search stored bodies. They work only when:

  1. the caller has content:read (owner, admin, developer), else 403 content_forbidden;
  2. the query is scoped to one org, else 400 content_needs_org;
  3. the org keeps content, else 409 content_logging_off;
  4. the deployment can open sealed bodies, else 503 vault_not_configured.

Bodies are sealed per org, so the server opens at most 500 candidate rows per page (newest first, after the other filters) and keeps those where every content term matches. Matching rows carry matches: [{field, snippet}]. A page can hold fewer rows than asked: follow next_cursor. Content terms must stand alone at the top level (ANDed, optionally negated) and cannot be combined with an aggregation. Every content search writes a content.searched audit row, without the search text.

Results

  • Rows (no aggregation): newest first, keyset-paged. Each row has id, ts, team, key, session, path, model, served_model, served, mode, daemon, region, provider, status, error, reason, fallback, attempts, tokens_in, tokens_out, cached, cost, ttft, latency, route_ms, has_content.
  • Table (count, stats, top): one row per group. Percentiles are continuous; distinct(f) counts distinct values. Default order: the first aggregate, descending.
  • Timeseries: one value per bucket per series (0 for count and sum when empty). The bucket is picked for 60 to 120 points unless you give one; at most 10 series, the rest summed as (other).

Money is in US dollars, durations in ms, times in ISO 8601. Each column has a type: string, int, ms, usd, tokens, count, number, time, bool.

Limit Default Cap
rows per page 50 (limit or | limit N) 500
groups (count by, top) 100 (top: 10) 1,000
group-by fields 3
timeseries points 60 to 120 1,000
custom-sort paging 10,000 rows
window 24 hours 90 days
statement time 5 seconds, then 504 query_timeout

The query API

The console uses /api/console/logs/* with its session; scripts use the same routes under the admin API.

Route What it does
GET /api/admin/v1/logs/query?q=&cursor=&limit=&tz= run a query
GET /api/admin/v1/logs/suggest?q=&pos= completions at the cursor position pos (UTF-16 offset)
GET /api/admin/v1/logs/fields the field registry, for a help panel
GET /api/admin/v1/logs/facets?q=&fields=&tz= per field, top values or number stats over the matched rows
GET /api/admin/v1/logs/patterns?q=&tz= matched rows grouped into request shapes
GET /api/admin/v1/logs/live?q=&cursor= the live feed: rows that finished since the cursor
GET, POST /api/admin/v1/logs/saved; PATCH, DELETE /api/admin/v1/logs/saved/{id} saved queries

The operator adds tenant=<org id> to narrow to one org; for everyone else the scope comes from the credential and cannot be widened by the query.

A query answer:

{
  "object": "venom.logs.query",
  "query": "status:5xx | count by model",
  "canonical": "status:5xx | count by model",
  "diagnostics": [],
  "window": {"since": "2026-11-02T09:00:00.000Z", "until": "2026-11-03T09:00:00.000Z", "tz": "UTC", "defaulted": true, "clamped": false, "label": "last 24h (default)"},
  "result": {"kind": "table", "columns": [{"name": "model", "type": "string"}, {"name": "count", "type": "count"}], "rows": [{"model": "gpt-5.5", "count": 12}], "truncated": false},
  "timing": {"parse_ms": 0.4, "db_ms": 18, "total_ms": 21}
}

result.kind is rows (with rows and next_cursor), table, or timeseries (with buckets, interval_ms and series). next_cursor is opaque: it freezes the first page's window and is bound to the query, zone and scope.

Saved queries are stored canonical: POST {name, query, shared?} (409 name_taken; at most 200 per person). Only the author, or someone with org:manage for a shared query, can change or delete one.

The live feed returns at most 100 rows a poll plus more and total; poll every 2 seconds while rows come. Its filter cannot have pipes (live_pipeline), a window (live_window) or content terms (live_content). A developer or viewer sees only requests from their own keys (own: true).

Errors

Status code When
400 invalid_query the query has an error; error.diagnostics lists each with a code, message, span and often a fix
400 cursor_mismatch, invalid_cursor a cursor from another query, or a malformed one
400 content_needs_org content search without one org in scope
403 content_forbidden content search without content:read
403 forbidden no logs:read
409 content_logging_off the org does not keep content
503 vault_not_configured the deployment cannot open sealed content
504 query_timeout the query ran over 5 seconds: narrow the window or add filters

Diagnostic codes are stable: unknown_field, unknown_macro, unknown_stage, unknown_function, missing_value, invalid_value, invalid_operator, unclosed_paren, unterminated_quote, nested_window, not_groupable, not_aggregatable, not_sortable, too_many_groups, too_long, operator_only, content_placement, content_aggregation, invalid_tz and more. Typos in field names, values, macros, stages and functions come with a "did you mean".