Skip to main content
Use the Query Guide API when you want an agent or automation to discover the best Squasher endpoints before it starts debugging.

​
Get query surfaces

The response lists the main query surfaces for a project, including:
  • logs
  • metrics and metric timelines
  • traces
  • errors and raw events
  • AI observability
  • monitors
  • incidents
Each surface includes a canonical path, a parameter list, and example investigation URLs. For metric timelines, the guide now points at the same generic metric series path the dashboard uses. That means automations and dashboard widgets can both request avg, count, sum, p50, p90, p95, and p99 over the same OTLP metric names instead of relying on product-specific endpoints.

​
Safe SQL schema

The schema response describes Squasher’s public observability query model. The safe query API and MCP Code Mode schema.get operation use the same model, so agents see the same column map that the validator enforces. Queryable tables:
  • logs
  • spans
  • metric_gauge_points
  • metric_sum_points
  • metric_histogram_points
  • metric_exponential_histogram_points
Queries that reference an unknown column on these tables are rejected before execution with UNKNOWN_COLUMN and a suggested nearby column when one is available.

​
Safe SQL queries

Request body:
The sql field is required. long_range is optional and only extends the allowed time window for projects that need a 30-90 day query. Both endpoints validate the SQL against the public schema, inject the project scope, and reject unsupported fields or shapes with a structured 400 response instead of executing untrusted input directly. Safe-query responses are limited to 10,000 rows and 8 MiB. If the serialized result exceeds the byte limit, the API returns 400 with error: "QUERY_RESULT_TOO_LARGE". Select fewer fields, aggregate before returning rows, or narrow the time window and retry. The TypeScript client exposes this response through the public QueryError type, and the CLI prints the same recovery guidance. Every physical table scan must have a positive lower timestamp bound in its WHERE clause. A timestamp expression in SELECT, under NOT, or in only one side of an otherwise-unbounded OR does not satisfy the guard. Multi-table joins are rejected; issue separate bounded queries and correlate their returned IDs instead. This keeps agent-generated SQL inside predictable ClickHouse Cloud scan limits. Use the CLI when an agent or script already has a safe SQL statement and needs JSON back from the public API:
Pass exactly one of --sql or --file. The CLI sends the same request body as the API examples above, and --long-range only adds "long_range": true when the flag is present.

​
Monitor queries

Common list parameters:
  • q - search name, target, linked component, incident id, and runbook URL
  • kind - monitor kind such as http, ssl, dns, or heartbeat
  • status - healthy, degraded, failed, or paused
  • enabled - true or false
  • limit
  • offset
Create and upsert requests use { name, kind, target, config, enabled?, linkedComponent?, runbookUrl? }. upsert matches by monitor name so scripts and agents can safely refresh declarative monitor config without double-creating the same check.

​
Incident queries

Common list parameters:
  • {incident_id} accepts the project-scoped incident ID returned by the API, for example inc_7. Existing UUID incident links remain accepted for compatibility.
  • q - search title, summary, assignee, root cause, and monitor metadata
  • status - investigating, identified, monitoring, or resolved
  • severity - low, medium, high, or critical
  • monitor_id - limit results to one linked monitor
  • limit
  • offset
The incident detail response includes timeline events, evidence records, recent monitor checks, and service attribution with owner-team metadata so agents can build investigation context without scraping the dashboard. Use comments and assignee updates for responder coordination. Comment create and delete calls need a user-authenticated actor, such as OAuth, because comments are attributed to a team member. Use the service attribution resolver when an agent has a monitor, trace, alert, repository, status component, or runbook signal but no incident row yet. The request body accepts monitorId, monitorName, traceServiceName, explicitServiceName, statusComponentName, repository, runbookUrl, and alertFields entries such as { "path": "service.name", "value": "checkout-api" }. The response uses the same service attribution object returned by incident detail. Use service ownership import candidates to preview operational services and link payloads from monitors and status components that are not assigned to a service yet. Each candidate includes a deterministic suggestedSlug, proposed monitor/status component IDs, source records, and existingServiceId when the slug already matches a service that should be linked instead of duplicated. Apply a candidate with POST /v1/projects/{project_id}/service-ownership/import-candidates/{suggested_slug}/apply to create the suggested service or merge its aliases and source links into the matching existing service. Use the service ownership debt endpoint to find only ownership gaps Squasher can prove from current product data: services missing owner teams, services missing runbooks, monitors not linked to an operational service, and status components not linked to a service. Use the service ownership teams endpoint to list owner teams available for service assignment. Create owner teams with { name, slug, description? }. If a retry hits an existing team with the same slug, the API returns that existing team. Patch the same fields on a team by id to keep ownership metadata current. Delete a team by id when it should no longer own operational services; existing service owner references are cleared. Use the service ownership services endpoint to list the current operational service graph, including aliases, repositories, monitor links, status component links, dependency service ids, runbooks, dashboards, and owner-team metadata. Create service ownership records with { name, slug, description?, ownerTeamId?, runbookUrl?, dashboardUrl? }. If a retry hits an existing service with the same slug, the API returns that existing service. Patch the same fields on a service by id to update ownership metadata without replacing links. Replace service links with { aliases, repositories, monitorIds, statusComponentIds, dependencyServiceIds }; the link update is a full replacement so pass empty arrays for link sets you want to clear. Delete a service by id when an operational service should no longer participate in incident ownership or routing.

​
Agent handoff

This should be the first API an agent calls when it is unsure which observability surface to use:
For MCP, call search("queryGuide"), search("schema.get"), search("query.run"), or search("query.explain") before executing Code Mode snippets. Keep safe SQL bounded by time and project scope.