Get result manifest

GET

/api/v1/bi/queries/{id}/result-manifest

Code sample: cURL

curl 'https://api.justcrawl.io/api/v1/bi/queries/$JOB_ID/result-manifest' \
  -H 'Authorization: Bearer $JUSTCRAWL_API_KEY'

• Production

Everything needed to plan pagination and render a freshness hint without fetching a page of rows. freshnessSec is an upper bound on how stale the underlying data may be and maxQuerySec is the time limit that applied — both are expressed as data properties because which engine ran the query is not part of the contract.

rowCount, byteSize, completedAt, and totalPages are null until the query reaches success.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Query Parameters

pageSize

integer

Logical rows per page used to calculate totalPages (default 200, max 1000)

Responses

200

Result manifest

Media typeapplication/json

object

manifest

required

object

status

required

string

Allowed values: queued running success failed canceled

rowCount

integer

nullable

byteSize

integer

nullable

completedAt

string format: date-time

nullable

freshnessSec

required

Upper bound, in seconds, on how far behind live the data may be.

integer

maxQuerySec

required

Time limit that applied to this query.

integer

totalPages

integer

nullable

pageSize

required

integer

Example

{
  "manifest": {
    "status": "queued"
  }
}

401

Missing or invalid authentication token

Media typeapplication/json

object

error

string

Example

{
  "error": "Missing or invalid authentication token"
}

403

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.

Media typeapplication/json

object

error

required

object

code

required

Stable, machine-readable error code. Match on this, not on message.

string

message

required

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.

string

docs_url

required

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.

string format: uri

request_id

required

Correlation id. Identical to the X-Request-ID response header — quote either one to support.

string

error

required

object

code

string

Allowed values: no_org feature_disabled insufficient_permissions email_not_verified authentication_required user_not_found rls_denied kill_switched

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"
  }
}

404

Not found, or not owned by your organization. The two are deliberately indistinguishable so cross-tenant existence cannot be probed

Media typeapplication/json

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

error

required

object

code

required

Stable, machine-readable error code. Match on this, not on message.

string

message

required

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.

string

docs_url

required

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.

string format: uri

request_id

required

Correlation id. Identical to the X-Request-ID response header — quote either one to support.

string

Example

{
  "error": {
    "code": "not_found",
    "message": "Query not found",
    "docs_url": "https://docs.justcrawl.io/guides/errors/not_found",
    "request_id": "req_9f3a1c7e2b40"
  }
}

500

Unexpected server error. Full detail goes to the logs and PostHog $exception capture, never the response

Media typeapplication/json

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

error

required

object

code

required

Stable, machine-readable error code. Match on this, not on message.

string

message

required

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.

string

docs_url

required

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.

string format: uri

request_id

required

Correlation id. Identical to the X-Request-ID response header — quote either one to support.

string

Example

{
  "error": {
    "code": "internal_error",
    "message": "Failed to list queries",
    "docs_url": "https://docs.justcrawl.io/guides/errors/internal_error",
    "request_id": "req_9f3a1c7e2b40"
  }
}