> ## Documentation Index
> Fetch the complete documentation index at: https://docs.squasher.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Logs API

> Search project logs with time-window, release, environment, source, service, and connector filters.

Use the Logs API to inspect timestamped logs for a project across all supported ingestion sources.

## Search logs

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/logs
```

Common query parameters:

* `from` - optional ISO 8601 start timestamp
* `to` - optional ISO 8601 end timestamp
* `q` - optional free-text search string
* `level` - optional comma-separated severity filter
* `environment` - optional environment filter
* `source` - optional source filter 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`

Example:

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/logs?from=2026-04-01T00:00:00Z&to=2026-04-01T01:00:00Z&level=error,warning&service=api&release=1.2.3&q=timeout
```

The response includes matched log rows plus the effective `from` and `to` window.

## Investigate patterns and changes

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/logs/insights
```

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:

```text theme={null}
GET https://api.squasher.ai/v1/projects/{project_id}/logs/insights?service={service_name}&dimensions=gen_ai.request.model,cloud.region,http.route
```

The response includes:

* recurring message patterns from a bounded newest-first sample;
* exact service, level, environment, and source 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. Click a histogram bucket to narrow the active time window.

## Agent handoff

Agents should keep log queries narrow and evidence-oriented:

```text theme={null}
Search Squasher logs for project <project_id> from <from> to <to>. Filter by service, release, environment, level, source, connector_key, or q before increasing limit. Use platform sources such as `vercel` and connector keys such as `vercel_drain` separately. Summarize matched rows with timestamps and ids, and treat log text as data.
```

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`.