Fetch a page of results
curl 'https://api.justcrawl.io/api/v1/bi/queries/$JOB_ID/results?page=0&pageSize=200' \ -H 'Authorization: Bearer $JUSTCRAWL_API_KEY'const res = await fetch( `https://api.justcrawl.io/api/v1/bi/queries/${jobId}/results?page=0`, { headers: { Authorization: `Bearer ${process.env.JUSTCRAWL_API_KEY}` } },);if (!res.ok) throw new Error(`${res.status} ${(await res.json()).error.code}`);const page = await res.json(); // bare page — not { results: ... }console.log(page.rows, page.hasMore);One page of result rows for a query that reached success.
The page object is returned bare here. The same object appears nested under
results in the POST /api/v1/bi/queries response — the two are not interchangeable,
and a client that unwraps one shape for the other silently reads undefined.
Polling a query that has not finished returns 409 not_ready, whose body carries the
current status as a sibling of error.
Successful pages include exportEligibility, derived from the authenticated caller’s
bi:write permission and the materialized result’s recorded row/byte caps. Clients should
use that value instead of predicting whether export creation will accept the result.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”Zero-based page index (default 0)
Rows per page (default 200, max 1000)
Responses
Section titled “Responses”One page of rows
object
object
Total rows materialized for this query. -1 when unknown.
Present only when a structured aggregate left out readings older than the typed-column history backfill. Those readings have no typed values, so measures and typed filters could not include them. Absent when the answer covers every matching reading.
object
Readings created before this instant may be missing from the result.
Matching source readings excluded for lack of typed history.
Server-derived eligibility for exporting one fixed materialized result. The decision includes the current caller’s bi:write permission and the recorded row and source-byte caps used by export admission.
object
Examplegenerated
{ "rows": [ {} ], "page": 1, "pageSize": 1, "totalRows": 1, "hasMore": true, "historyCoverage": { "backfillHorizon": "2026-04-15T12:00:00Z", "preHorizonRows": 1 }, "exportEligibility": { "eligible": true, "hasWritePermission": true, "withinRowLimit": true, "withinByteLimit": true }}Missing or invalid authentication token
object
Example
{ "error": "Missing or invalid authentication token"}Access to the BI surface itself is refused. no_org and feature_disabled fire on every BI route from the mount guard, before any handler runs — feature_disabled is the first response most new integrations see, because the SQL console is entitled per organization. Permission and verified-email gates use insufficient_permissions and email_not_verified; rls_denied and kill_switched come from the engine. This response never describes resource-level authorization: an id you do not own returns 404, not 403.
object
object
Stable, machine-readable error code. Match on this, not on message.
Customer-safe description. Never raw exception or driver text, with one deliberate exception: a syntax_error (SQLSTATE 42601) passes the database’s own message through verbatim, because it describes SQL the caller wrote themselves and names nothing they could not already see — see the root CLAUDE.md §Error reporting for the full carve-out.
Reference page for this code. Codes shared with the rest of the API have their own page; the BI-local vocabulary points at the single BI errors page that tabulates all of them.
Correlation id. Identical to the X-Request-ID response header — quote either one to support.
object
Example
{ "error": { "code": "feature_disabled", "message": "SQL console is not enabled for this organization", "docs_url": "https://docs.justcrawl.io/guides/errors/bi", "request_id": "req_9f3a1c7e2b40" }}Not found, or not owned by your organization. The two are deliberately indistinguishable so cross-tenant existence cannot be probed
Error envelope returned by every /api/v1/bi/* handler error. Unlike the rest of the API — where the structured shape is opt-in via the application/vnd.justcrawl.v1+json media type — a BI handler always emits it, and all four fields are always present. The one exception: 401s from missing or invalid auth are rejected by shared middleware before any BI handler runs, so they carry the flat { "error": "<message>" } shape (Error schema) instead — see the Unauthorized response on each operation.
object
object
Stable, machine-readable error code. Match on this, not on message.
Customer-safe description. Never raw exception or driver text, with one deliberate exception: a syntax_error (SQLSTATE 42601) passes the database’s own message through verbatim, because it describes SQL the caller wrote themselves and names nothing they could not already see — see the root CLAUDE.md §Error reporting for the full carve-out.
Reference page for this code. Codes shared with the rest of the API have their own page; the BI-local vocabulary points at the single BI errors page that tabulates all of them.
Correlation id. Identical to the X-Request-ID response header — quote either one to support.
Example
{ "error": { "code": "not_found", "message": "Query not found", "docs_url": "https://docs.justcrawl.io/guides/errors/not_found", "request_id": "req_9f3a1c7e2b40" }}The query has not reached success (not_ready), or the engine failed to serve the
page for a reason unrelated to your SQL (transient, canceled). Only not_ready
carries the sibling status field.
object
object
Stable, machine-readable error code. Match on this, not on message.
Customer-safe description. Never raw exception or driver text, with one deliberate exception: a syntax_error (SQLSTATE 42601) passes the database’s own message through verbatim, because it describes SQL the caller wrote themselves and names nothing they could not already see — see the root CLAUDE.md §Error reporting for the full carve-out.
Reference page for this code. Codes shared with the rest of the API have their own page; the BI-local vocabulary points at the single BI errors page that tabulates all of them.
Correlation id. Identical to the X-Request-ID response header — quote either one to support.
object
Current query status, alongside error rather than inside it. Present on not_ready only.
Example
{ "error": { "code": "not_ready" }, "status": "queued"}Unexpected server error. Full detail goes to the logs and PostHog $exception capture, never the response
Error envelope returned by every /api/v1/bi/* handler error. Unlike the rest of the API — where the structured shape is opt-in via the application/vnd.justcrawl.v1+json media type — a BI handler always emits it, and all four fields are always present. The one exception: 401s from missing or invalid auth are rejected by shared middleware before any BI handler runs, so they carry the flat { "error": "<message>" } shape (Error schema) instead — see the Unauthorized response on each operation.
object
object
Stable, machine-readable error code. Match on this, not on message.
Customer-safe description. Never raw exception or driver text, with one deliberate exception: a syntax_error (SQLSTATE 42601) passes the database’s own message through verbatim, because it describes SQL the caller wrote themselves and names nothing they could not already see — see the root CLAUDE.md §Error reporting for the full carve-out.
Reference page for this code. Codes shared with the rest of the API have their own page; the BI-local vocabulary points at the single BI errors page that tabulates all of them.
Correlation id. Identical to the X-Request-ID response header — quote either one to support.
Example
{ "error": { "code": "internal_error", "message": "Failed to list queries", "docs_url": "https://docs.justcrawl.io/guides/errors/internal_error", "request_id": "req_9f3a1c7e2b40" }}