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.
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:
- the caller has
content:read(owner, admin, developer), else403 content_forbidden; - the query is scoped to one org, else
400 content_needs_org; - the org keeps content, else
409 content_logging_off; - 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
countandsumwhen 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".
Related
- Venom Cloud APIs overview for credentials and roles.
- Log query language for the language as the console's Requests page, alerts and live feed use it.