Get query status

GET

/api/v1/bi/queries/{id}

Code sample: cURL

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

• Production

Current status of one submitted query — the endpoint you poll after a submit that did not complete inline. The status object is returned bare, not wrapped. A query belonging to another organization returns 404, never 403.

Authorizations

• bearerAuth

Parameters

Path Parameters

id

required

string format: uuid

Responses

200

Current status

Media typeapplication/json

object

jobId

required

string format: uuid

status

required

string

Allowed values: queued running success failed canceled

queuePosition

Position in your organization’s queue. Present only while status is queued.

integer

startedAt

string format: date-time

finishedAt

string format: date-time

rowCount

integer

bytesScanned

Informational only; not billed and not enforced.

integer

sql

required

Raw SQL for SQL submissions; null for structured definitions.

string

nullable

sqlPreview

required

Display-only rendered SQL for structured definitions; null for raw SQL submissions.

string

nullable

label

required

The saved-query label at submit time, or null if none was given.

string

nullable

error

object

code

string

Allowed values: syntax_error statement_timeout rls_denied too_many_queries kill_switched canceled transient

message

string

retriable

boolean

Example

{
  "status": "queued",
  "error": {
    "code": "syntax_error"
  }
}

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