# API reference > The read API for scripts, pipelines and headless agents: getting a token, the conventions, every endpoint with its parameters, example responses, the limits and the investigation method. The read API for scripts, pipelines and headless agents. Every endpoint is a `GET` that answers in JSON, with a text mode for reading lines, and every one reads the whole account: every source, and every event within retention. A coding agent in an editor or a chat client does not need any of this - it connects through the MCP server with no token, and its tools are these endpoints under the same names. See [MCP server](https://app.sanelog.com/docs/mcp.md#connecting-to-the-mcp-server). An introduction to SaneLog for an agent is at [https://app.sanelog.com/llms.txt](https://app.sanelog.com/llms.txt). ## Getting a token An Account Admin creates a token under **Account > API tokens** (see [API tokens](https://app.sanelog.com/docs/account.md#api-tokens)). Give it to the script or agent in its environment as `SANELOG_API_TOKEN`. The base URL is `https://app.sanelog.com/api/v1`, and `/me` confirms the token works and names the account: ```bash export SANELOG="https://app.sanelog.com/api/v1" curl -sH "Authorization: Bearer $SANELOG_API_TOKEN" "$SANELOG/me" ``` The answer names the account, its retention and timezone, the token, the level names and the rate limit: ```json { "account": { "name": "Example Co", "retention_days": 30, "timezone": "Australia/Sydney" }, "token": { "name": "CI runner", "scopes": ["read"], "created_by": "alex@example.com", "expires_at": null }, "levels": ["debug", "info", "notice", "warning", "error", "critical", "alert", "emergency"], "rate_limit": { "per_token_per_minute": 120 }, "server_time": "2026-09-06T09:14:00Z", "docs_url": "https://app.sanelog.com/docs/api-reference", "about_url": "https://app.sanelog.com/llms.txt", "mcp_url": "https://app.sanelog.com/mcp" } ``` ## Conventions ### Authentication Every request carries `Authorization: Bearer `. Tokens belong to the account (created under Account > API tokens by an Account Admin) and read that account only. A token can be restricted to a list of IP addresses, and calls from any other address are then a 403. Keep the token in the environment as `SANELOG_API_TOKEN`, and never write it into code or logs. ### Unknown parameters are rejected A parameter the endpoint does not accept is a 400 whose `error.valid` lists the accepted names. Read it and correct the call rather than guessing. ### The effective query is echoed Every response carries `query`: the window actually used, the sources the scope resolved to, the limit applied, and `clamped: true` when any of them differs from what was asked (a window past retention is cut to retention). Check it before drawing a conclusion from an empty result. ### Dropped events are reported Every response over a window (`events`, `histogram`, `facets`, `summary`, `context`) carries `dropped`: how many events a config set refused at ingest inside that window, scoped like the response, and when there were any, one entry per source with the count, the reasons, the first and last minute it happened and, when flood drops are among them, the flood limit (events a minute) and config set the source has now - the limit at the time is not recorded, so after a change the figure is the current one. Those events were never stored, so every count and line in the response is what was kept, not what was sent. A source over its flood limit keeps at most the limit each minute, so a count sitting at the limit is the limit, not the sender's rate, and the lines over it are gone rather than quiet. Older than 89 days the drops are counted in whole hours, so the first and last minute can lie up to an hour outside a window that old. The key is absent when the ingest counters could not be read. Text responses carry the same as `# dropped` lines under the header. ### Times ISO 8601 in UTC in every response. Requests accept ISO 8601 with an offset or Z (`2026-09-06T09:14:00Z`, `2026-09-06T19:14:00+10:00`) or a relative `since=15m|2h|1d`. Every event carries `time` (the sender's clock) and `received_at` (when SaneLog received it). Prefer `received_at` when two sources disagree by more than a second. ### Identifiers Sources and filters are addressed by name or uuid, and `source` also takes a name glob (`prod-*`). Events are addressed by their uuid, which every line and object carries. Anything outside your account is a 404, never a 403. ### Levels Severities in order: debug, info, notice, warning, error, critical, alert, emergency. `min_level=warning` means warning and above (what an investigation nearly always wants), and `level=error,critical` is an exact set. ### Query expressions Plain text in `q` searches the message for that text, ignoring case. Text that contains an operator word (`is`, `contains` or `does`), or that starts with a quote or a parenthesis, is read as a query expression. [Query expressions](https://app.sanelog.com/docs/query-expressions.md#writing-an-expression) has the full grammar with worked examples. An expression is the only way to say "or" and "not" through the API: ```bash curl -sG -H "Authorization: Bearer $SANELOG_API_TOKEN" "$SANELOG/events" \ --data-urlencode 'q=program is nginx and (level is error or message contains "upstream") and route does not contain "/health"' \ --data-urlencode 'since=2h' --data-urlencode 'format=text' ``` The other parameters narrow the results further, on top of the expression. The response shows how `q` was read: `query.expression` when it was read as an expression, or `query.q` when it was read as text to search for. An expression that cannot be read is refused with a `400` that names the position of the problem. To search for text that contains an operator word, put the whole text in quotes. `/filters` returns each saved filter's `expression` too, ready to paste into `q`. ### Output formats `format=json` (default) or `format=text`. Text is one event per line - ` ` - about a third of the tokens of JSON, with a `# key=value` header line echoing the query. Add `attributes=1` to append each event's attributes as compact JSON and `collapse=1` to fold consecutive lines with the same normalised message into one line with a `(xN)` count. Use text for reading lines, JSON for everything else. An `/events` answer in text format: ```text # sanelog events from='2026-09-06T07:14:00.000Z' until='2026-09-06T09:14:00.000Z' sources='all' limit=2 clamped=false has_more=true cursors={"before":"eyJkdCI6...","after":"eyJkdCI6..."} 2026-09-06T09:13:58.412Z 01a0c8bb-f376-7249-9bae-63f61d7e1752 web-1 nginx error upstream timed out while reading response header 2026-09-06T09:13:57.090Z 01a0c8bb-f221-70f3-b1dc-881792d126be web-2 laravel error SQLSTATE[HY000] [2002] Connection refused ``` ### Paging and limits `events` returns 100 rows by default and at most 500. `query.has_more` says whether the window holds more, and `query.cursors.before` / `query.cursors.after` are opaque cursors to pass back as `before=` (older) or `after=` (newer). Facets return at most 50 values. Prefer counts (histogram, facets) to paging through lines. ### Errors Always `{ "error": { "code", "message", "valid"? } }`: 400 (a parameter problem, the message says which), 401 (no token, or one that is unknown, expired or revoked), 403 (the request came from an address outside the token's allow list), 404 (not in your account), 429 (rate limited), 500 (retry, then report). ## Shared parameters `events`, `histogram`, `facets`, `summary` and the sweep of `context` accept these together, and every one given must match. A [query expression](https://app.sanelog.com/docs/api-reference.md#query-expressions) in `q`, or a saved filter, can express "or". | Parameter | Meaning | |---|---| | `source` | A source name, uuid or name glob (`prod-*`), repeatable or comma-separated. Omit for every source in the account. | | `filter` | A saved filter's name or uuid: its source scope and predicate apply. Given together with `source`, the two intersect. | | `environment` | A source environment as tagged in SaneLog (`production`, `staging`, ...), repeatable or comma-separated. Intersects with `source` and `filter`. `/sources` shows each source's environment, and asking for one no source carries is a 404 listing the ones in use. | | `q` | A case-insensitive substring of the message, or a query expression (see Query expressions) - `q=level is warning+ and program is not cron`. The only way to say "or" and "not". | | `program` | Exact program (the syslog tag / app name). | | `level` | An exact set of severities, comma-separated or repeated. | | `min_level` | This severity and above. | | `attr[path]=value` | The attribute at the dotted path equals the value (numbers and strings compare as text, so `attr[status]=500` matches both). | | `attr_contains[path]=value` | The attribute's text contains the value, case-insensitively. | | `present[]=path` or `absent[]=path` | The attribute path holds a value / holds none. | | `since` | A trailing span ending now: `15m`, `2h`, `1d`. Default `1h`. | | `from` or `until` | Explicit ISO 8601 bounds. `until` defaults to now. | ## Endpoints ### GET /me Orientation: the account (name, retention, timezone), the token, the level names, the rate limit, the docs URL. Call it once to verify the token. ```bash curl -sH "Authorization: Bearer $SANELOG_API_TOKEN" "$SANELOG/me" ``` ### GET /sources Every source in the account: uuid, name, `environment` (the tag the account gave it - `production`, `staging`, ... - or null when unassigned), `description` (what the account says it is for), how it is fed (`http` or `syslog`), `last_event_at`, `events_24h`, token status. The map of what the account holds: which sources are production and which are not, which belong to the project in question, which are channels (a CloudWatch forwarder, an EventBridge feed) rather than single servers, and which have gone silent. ```bash curl -sH "Authorization: Bearer $SANELOG_API_TOKEN" "$SANELOG/sources" ``` ### GET /filters Saved filters: name, scope (named sources, a name pattern, environments), a readable predicate, alert count. Any of them can be passed as `filter=`. ```bash curl -sH "Authorization: Bearer $SANELOG_API_TOKEN" "$SANELOG/filters" ``` ### GET /fields The attribute paths observed on events (types, events seen, first and last seen): what `attr[...]` and `facets?by=` can use. Parameters: `source`. ```bash curl -sH "Authorization: Bearer $SANELOG_API_TOKEN" "$SANELOG/fields?source=prod-*" ``` ### GET /events The search: matching events inside the window, newest first (oldest first when walking with `after`). Read lines in text format, collapsed, in a narrow window - never page through a whole window. `dropped` says what the window refused at ingest. Parameters: the [shared parameters](https://app.sanelog.com/docs/api-reference.md#shared-parameters), `limit`, `before`, `after`, `format`, `attributes`, `collapse`. ```bash curl -sH "Authorization: Bearer $SANELOG_API_TOKEN" "$SANELOG/events?since=2h&min_level=error&source=prod-*&format=text&collapse=1&limit=50" ``` A JSON answer carries the effective `query` and the events under `data`: ```json { "query": { "from": "2026-09-06T07:14:00.000Z", "until": "2026-09-06T09:14:00.000Z", "sources": ["web-1", "web-2"], "filter": null, "environments": null, "q": null, "expression": null, "program": null, "levels": ["error", "critical", "alert", "emergency"], "fields": [], "limit": 2, "clamped": false, "order": "newest_first", "has_more": true, "cursors": { "before": "eyJkdCI6...", "after": "eyJkdCI6..." }, "explorer_url": "https://app.sanelog.com/log-explorer?..." }, "data": [ { "id": "01a0c8bb-f376-7249-9bae-63f61d7e1752", "time": "2026-09-06T09:13:58.412Z", "received_at": "2026-09-06T09:13:58.431Z", "source": "web-1", "program": "nginx", "level": "error", "message": "upstream timed out while reading response header" }, { "id": "01a0c8bb-f221-70f3-b1dc-881792d126be", "time": "2026-09-06T09:13:57.090Z", "received_at": "2026-09-06T09:13:57.102Z", "source": "web-2", "program": "laravel", "level": "error", "message": "SQLSTATE[HY000] [2002] Connection refused" } ] } ``` ### GET /events/{id} One event with its attributes and an `explorer_url`. ```bash curl -sH "Authorization: Bearer $SANELOG_API_TOKEN" "$SANELOG/events/01a073f0-8943-7369-af3a-d891673c8aa1" ``` ### GET /histogram Counts per bucket across the window, plus `total`: the call that shows when something started. `bucket=1m|5m|15m|1h|1d`, or automatic. One call over a wide window is also the way to count matching events. `dropped` beside `total` says what the window refused at ingest: buckets sitting at a round number a minute may be a flood limit. Parameters: the [shared parameters](https://app.sanelog.com/docs/api-reference.md#shared-parameters), `bucket`. ```bash curl -sH "Authorization: Bearer $SANELOG_API_TOKEN" "$SANELOG/histogram?since=6h&min_level=warning" ``` ### GET /facets The top values of one field among the matches, with counts, `total` and `other`. `by=message` groups on the normalised message (numbers, ids, quoted strings replaced by `?`) - the call that answers "which errors". `by` also takes `source`, `program`, `level`, `sender_ip` or an attribute path. `dropped` beside `total` says what the window refused at ingest. Parameters: the [shared parameters](https://app.sanelog.com/docs/api-reference.md#shared-parameters), `by`, `limit`. ```bash curl -sH "Authorization: Bearer $SANELOG_API_TOKEN" "$SANELOG/facets?since=6h&min_level=error&by=message" ``` ### GET /summary The window folded into message patterns and clustered by their shared opening, grouped by program (`by=program`, default) or source, every count compared with the window of the same length before it - each group and cluster carries `count`, `previous`, `levels`, `severe` (lines at warning and above) and a `status` of new, stopped, rising, falling or steady. The call that answers "what is being logged, and what changed": one request describes a day or a week. Each cluster lists its `variants` (the patterns folded into it), `sources`, its newest `example` line and an `expression` that selects exactly its lines for `/events`. `sort=severity` puts the worst first, and `limit` is the number of clusters per group. `dropped` says what the window refused at ingest: a steady count at a round number a minute may be a flood limit. Parameters: the [shared parameters](https://app.sanelog.com/docs/api-reference.md#shared-parameters), `by`, `sort`, `limit`. ```bash curl -sH "Authorization: Bearer $SANELOG_API_TOKEN" "$SANELOG/summary?since=1d&min_level=warning&sort=severity" ``` ### GET /context The incident window around an event (`event=`) or a moment (`at=