Read API overview

The read API gives read access to a Squally organization’s test results, for scripts, CI jobs and AI agents. The base URL is https://app.squally.dev/api/v1. Every endpoint is listed in the API reference.

Authentication

Every request carries an organization read key:

Authorization: Bearer sqly_ro_…

• A read key is organization-wide - it reads every project of the organization.
• It is created by an organization admin in Settings → API keys.
• It expires after 30, 60, 90 or 180 days, as chosen when it is created.
• There is no renewal: create a new key and revoke the old one.
• Project ingest keys (sqly_…) are refused with wrong_key_type.

Expiry warning

From 7 days before a key expires, every authenticated response carries the Squally-Key-Expires-At header with the expiry instant (ISO-8601).

Rate limit

Currently 60 requests per 60 seconds per key, counted per Authorization header - a read key has its own budget, shared with nothing else. Over the limit the edge answers 429 without a JSON body and without Retry-After: back off for at least 60 seconds.

Plans

The read API is part of the Standard and Pro plans. A key of an organization on Free is answered 403 tier_too_low. Keys are not revoked on a downgrade and work again after an upgrade.

Errors

Every error has one shape:

{ "error": "<sentence>", "code": "<slug>" }

The sentence may be reworded; the slug may not - match on code. An id that does not exist and an id that belongs to another organization get the same 404, byte for byte.

Test names in paths

Test names are Playwright title paths and often contain /. URL-encode them, including / as %2F.

Sharded runs

Sharded runs are returned as one logical run: /runs lists one row per logical run, and the run routes answer for all shards, whichever shard’s id you pass.

Stability

v1 is in beta. The API may change until the beta ends; every change is listed in the changelog.