---
title: Log queries over the admin API
description: 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.
section: cloud
order: 410
audience: [user, operator, builder, agent]
sources: [docs/cloud-log-query.md, services/nodejs-cloud/lib/logquery, services/nodejs-cloud/app/api/admin/v1/logs]
features: [cloud.log-query]
---

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](/docs/cloud/console-log-query.md); the logs routes themselves are listed on the admin API's
logs page.

## Examples {#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:

```bash
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'
```

```ts
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](/docs/cloud/api-overview.md#admin-credentials). Every
logs route needs `logs:read`.

## The query language {#language}

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

## Content search {#content}

`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 {#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 {#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:

```json
{
  "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 {#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 {#related}

- [Venom Cloud APIs overview](/docs/cloud/api-overview.md) for credentials and roles.
- [Log query language](/docs/cloud/console-log-query.md) for the language as the console's Requests page, alerts and live feed use it.
