Skip to content
justcrawl.io

List submitted queries

GET
/api/v1/bi/queries
Code sample: cURL
curl 'https://api.justcrawl.io/api/v1/bi/queries?limit=20' \
  -H 'Authorization: Bearer $JUSTCRAWL_API_KEY'

Query history for your organization, newest first. Which engine executed a query is deliberately not surfaced — routing is transparent, and freshness and timeout hints come from GET /api/v1/bi/queries/{id}/result-manifest instead.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer

Rows to return (default 50, max 200)

submissionKey
string format: uuid

Exact tenant-scoped lookup by Idempotency-Key, independent of newer history. Returns zero or one query.

Responses

Section titled “Responses”

200

Section titled “200”

Query history

Media typeapplication/json
object
queries
required
Array<object>

One row of the submitted-query history (GET /api/v1/bi/queries). Routing is transparent: the engine that executed the query is never surfaced.

object
id
string format: uuid
userId
string format: uuid
status
string
Allowed values: queued running success failed canceled
label
string
nullable
sql
string
nullable
sqlPreview

Display-only rendered SQL for a structured definition. Never accepted as query input.

string
nullable
rowCount
integer
nullable
resultByteSize
integer
nullable
errorCode
string
nullable
submissionKey
string format: uuid
nullable
scopeKind
string
Allowed values: org agent
scopeAgentId
string format: uuid
nullable
sqlDialect
string
nullable
Allowed values: postgres
contentKind
string
Allowed values: sql definition
submittedAt
string format: date-time
startedAt
string format: date-time
nullable
finishedAt
string format: date-time
nullable
Example
{
  "queries": [
    {
      "status": "queued",
      "scopeKind": "org",
      "sqlDialect": "postgres",
      "contentKind": "sql"
    }
  ]
}

400

Section titled “400”

Invalid submission key

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
Examplegenerated
{
  "error": {
    "code": "example",
    "message": "example",
    "docs_url": "https://example.com",
    "request_id": "example"
  }
}

401

Section titled “401”

Missing or invalid authentication token

Media typeapplication/json
object
error
string
Example
{
  "error": "Missing or invalid authentication token"
}

403

Section titled “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"
  }
}

500

Section titled “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"
  }
}