Skip to main content
Search log lines with the Public API (V2). This is the way to query logs programmatically, including structured (JSON) log data. The GraphQL API does not expose log lines.
If you’re building an AI agent or assistant, AppSignal MCP exposes log search and other monitoring data to agents directly, without calling this API yourself.

Finding your site and source IDs

A log search needs a site_id and one or more source_ids. Both appear in the URL of a log source in AppSignal. Open a log source and read them from the path:

Search log lines

For every field of the request and response, see the Search log lines reference. The request takes a site_id, the source_ids to search, a query, and a pagination object. Include at least one source ID: an empty source_ids list returns no lines. An empty query matches every line. See query language. from defaults to the start of your log retention, and to defaults to now. pagination takes per_page (number), order (ASC or DESC), and a cursor with a time and an id. Set both to null for the first page. To fetch the next page, send the timestamp and id of the last line you received as cursor.time and cursor.id. Without the id, lines that share that timestamp are skipped.

Example request

The endpoint returns an array of log lines. Each line’s structured data is in its json field, as a JSON-encoded string. To count lines or average a field instead, query log metrics.
Structured fields such as status_code, path, or detail live in the json field. Query them by their exact key as it appears in your log’s JSON (for example, status_code=401 or detail.message:"required").

Query language

The query string supports boolean logic over log line fields and the structured json body.

Operators

String operators (=, !=, :, !:) compare both sides as strings. Numeric operators (>, >=, <, <=) cast both sides to a number; if a value cannot be parsed as a number, that log line is skipped.

Combining expressions

  • AND / OR: severity=error AND hostname:web, or severity=info OR severity=warn.
  • Implicit AND: a space between expressions means AND. severity=error hostname:web is the same as severity=error AND hostname:web.
  • Nesting with parentheses: message:"API request" AND (severity=info OR severity=warn).
  • Precedence: AND binds tighter than OR.
Any operator can be used inside an OR group, not only equality — for example, message:"API request" AND (user.id>1000 OR user.email:"example.com").

Fields

Given a log line with this JSON body:
  • Base fields: message, severity, hostname, and group match the log line’s top-level fields.
  • Nested JSON: use dot notation to reach into the json body, such as status_code=200 or user.id=12345.
  • JSON arrays: index array elements, such as user.roles.0=admin.
  • Escaped dots: to match a literal dot in a key name, escape it. user.location\.country=US matches the key location.country inside user, rather than a nested country object.
  • Default field: a bare term with no field matches message with the contains operator. timeout is the same as message:timeout.
Reference a field directly by its name in your log’s JSON, without a type suffix. See legacy query syntax if you have older queries.

Quoting values

Wrap values that contain spaces or parentheses in double quotes. Otherwise the space splits the value into separate expressions joined by implicit AND.
Only double quotes are recognized. Inside a quoted value, escape a quote with \" and a backslash with \\. For example, message:"value with \"quotes\"" matches the text value with "quotes".

Legacy query syntax

Older queries stored attributes as typed fields, so they had to prepend attributes., append a type suffix (_string, _int), and use a [ ] list for multiple values. The current query language removes all three — reference fields directly and use OR instead of a list:
The API no longer reads the legacy syntax, and no longer rejects it either. attributes. is now an ordinary path into your log’s JSON. So attributes.user_id_int=12345 looks for a user_id_int key inside an attributes object. A filter in the old attributes. form matches nothing, instead of returning an error. If your logs contain an attributes object, you can filter on its fields, such as attributes.user_id=12345.