Skip to main content
The logs API reads the logs of a project from every ingest source: SDKs, OpenTelemetry, and log drains. Use it to search logs, chart their volume, and find patterns and changes. For field design and sampling, see Design Queryable Logs.

​
Search logs

Common query parameters:
  • from - optional ISO 8601 start timestamp
  • to - optional ISO 8601 end timestamp
  • q - optional free-text and fielded search string (see Search syntax)
  • level - optional comma-separated severity filter, in any case (ERROR matches error)
  • environment - optional environment filter
  • source - optional comma-separated source filters such as otel, vercel, or railway
  • service - optional service.name filter
  • release - optional release or service.version filter
  • connector_key - optional connector filter
  • limit
  • offset
  • tags - optional: all (default) or summary; see Row attributes
  • tag_paths - optional, with tags=summary: up to 20 comma-separated attribute paths
Example:

​
Search syntax

q accepts free-text tokens, field filters (level:error, service:api), wildcards (message:*Timeout*), and regular expressions written as field://pattern//:
Patterns use RE2 syntax, so matching time grows linearly with the text. A closing // must end the term. Lookaround and backreferences are not supported. A regex filter reads more data than a token search. Use a narrow time window and add other filters, such as service or level, on wide searches. The response includes matched log rows plus the effective from and to window. Rows are newest first. total is offset plus the rows returned, plus one when more rows exist, so a client pages with offset until offset reaches total.

​
Row attributes

Each row carries its log attributes in tags under the full dotted key, for example {"http.route": "/checkout", "user.id": "42"}, plus trace_id, span_id, service_name, host_name, and session_id when the log has them. Values are strings: a number or a boolean comes back as its text. Array values are not included. A row from an older SDK can have the old and the current attribute name; read the current name.
  • tags=all (default) returns every attribute of each row.
  • tags=summary returns only the attributes that the row fields already summarize (such as http.route, http.request.method, http.response.status_code, exception.type, and error.type), squasher.skip_ingest, and the attributes you list in tag_paths. Summary pages read much less data, so they return faster on long windows. Use them for list views that show a few attribute columns, and get one log with every attribute when a reader opens it.
A tag_paths entry is an attribute path of letters, digits, and _ . : / -, up to 128 characters. A path also reads the older names of an OpenTelemetry attribute, so http.request.method returns the value of a log that has only http.method. An attribute that a row does not have is not in its tags. Paths that together need too large a read return 400; request fewer or shorter paths.

​
Get one log

Returns one log with every attribute as data, in the same row shape as search. Use the event_id and timestamp (Unix milliseconds) of a search row. ts is required: it lets the read go straight to that millisecond. The response is 404 when the project has no log with that event_id at that ts, and 400 when event_id is not a UUID or ts is missing.

​
Chart log volume

Use the same field and time filters as log search. Add group_by to split each time bucket by service, http_method, service_version, environment, level, or source. Add step to use an explicit bucket size of 1m, 5m, 15m, 1h, 6h, or 1d:
Each grouped bucket has a group value. The response also has the effective granularity and group_by. The API rejects a step that creates more than 2,000 buckets for the requested range.

​
Investigate patterns and changes

Use the same from, to, q, level, environment, source, service, release, and connector_key filters as log search. Add dimensions with up to five comma-separated public log attribute paths to compare their top values between windows:
For a filter sidebar or another view that only needs exact current service, environment, source, connector, and level counts, set view=facets. This skips pattern analysis, custom dimensions, release counts, and the previous comparison window:
Facet counts read at most the newest 1.2 million logs of the window when they cannot use precomputed counts, which is always the case with q. When the counts cover only the newest part of the window, the response sets counts_from: current_total and the distributions then cover counts_from to to. Use the histogram endpoint for the full-window count of a text query. Use view=patterns to run only the bounded pattern analysis. It does not wait for current or previous-window distributions. Use view=changes for comparisons without pattern analysis. The default view=full runs both. Unrequested arrays are empty; uncomputed totals are zero, not measured event counts. In pattern mode, use sample_size for the sample count.
The full response includes:
  • recurring message patterns from a bounded newest-first sample;
  • exact service, level, environment, source, release, and connector distributions for the selected window;
  • the same exact built-in distributions for the immediately preceding equal-length window;
  • sampled requested-attribute distributions for both windows; and
  • explicit sample and total counts so clients can describe the evidence accurately.
Pattern analysis samples at most 10,000 matching logs and returns at most 50 patterns. Requested custom attribute distributions use the newest 10,000 matching logs from the selected window and the newest 10,000 from the preceding window before grouping. Custom rows set sampled: true, and custom_distribution_sample_limit reports that bound; built-in distributions and total counts stay exact. Use a narrow time range and field filters before widening an investigation. Attribute values are truncated to 256 characters and each distribution returns at most 12 values. Prefer low-cardinality operational attributes such as model, role, outcome, or region; do not aggregate user identifiers, request IDs, prompts, authorization data, or other sensitive/high-cardinality fields. The resolved insights window must be ordered (from cannot be after to) and cannot exceed 30 days. Omitting to uses the current time; omitting from uses 24 hours before the resolved to. Invalid, inverted, or oversized windows return HTTP 400 before a log query runs. The Squasher dashboard exposes the same workflow through the Results, Patterns, and Changes views on the Logs page. The volume chart can group the active query and use a selected time step. The compact filter sidebar counts every value over the whole time range and the current filters, not only the rows on screen. It has checkboxes for levels, services, environments, sources, and connectors, a search box for trace IDs and span IDs, and the attribute fields that appear most in the matching logs. Each search box searches all values of its field in the time range. A trace ID or span ID matches by its first characters. Attribute fields leave out Squasher’s own squasher.* fields and records marked "squasher.skip_ingest": true. Selected filters appear above the results as removable chips. Selecting an ID or an attribute value adds its field clause to the query, so you can combine several values with the direct filters. Use Reset to clear the complete filter set. Filter changes keep the Logs page open while Squasher refreshes the matching histogram, rows, and investigation data. The current log results stay visible during the refresh, and the status changes to Updating. This makes it possible to narrow an investigation without losing the open workflow. Selecting a log opens a full-height detail drawer on the right side. The drawer keeps the Logs page visible and preserves the selected event in the URL. Use Attributes for grouped event, trace, resource, and custom fields; structured JSON values expand in place. Use Trace to debug the linked trace and span, Related logs for correlated events, and Raw for the complete record. The drawer can copy the event JSON, a deep link, or an agent-ready prompt. Investigate opens the hosted Squasher Agent with the event context already in the composer. Trace details and related logs start loading when the drawer opens. Use the arrow keys or J and K to move between log events without closing the drawer. Use the separate disclosure control at the start of a row to expand the message, stack trace, and attributes without opening the drawer. The table can wrap long messages. Its searchable column control can pin up to eight direct or custom fields. These view settings stay in the Logs page URL. The compact result summary shows the visible and total rows plus query time; point to it or focus it to see scanned and returned row and byte counts.

​
Agent handoff

Agents should keep log queries narrow and evidence-oriented:
Use squasher logs search --project <project_id> ... for individual rows, squasher logs insights --project <project_id> --dimension <attribute> ... for normalized before/after comparisons, or MCP search("logs insights") followed by execute.

​
Dashboard investigation views

The log page opens on Events. Columns and Wrap lines are beside the view tabs. Use Volume for the log chart, Group by, and Step controls. The filter header and Reset stay in place while the filter values scroll. The Events rows load with summary attributes and the attribute columns you show, so long windows load fast. Columns offers the attributes of the selected window and of logs you have opened. When you open a log, its Attributes tab shows the summary at once and then every attribute. Switching between Lucene and SQL changes the editor without running a request. Select Run query to apply the query. Existing rows stay visible during a background refresh. Open Patterns, then Pattern details, for the example, first and last seen times, and sample count. Copy pattern for agent copies the normalized pattern, fixed time window, filters, project context, and API instructions. The agent can repeat the same bounded analysis and select the matching pattern. This is a sample, not an exhaustive list of all matching events.