Skip to content
justcrawl.io

List saved queries

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

Your organization’s saved queries, most recently updated first.

List rows omit shareToken by design. A share token is a live bearer capability — anyone holding one can read that query’s results with no credential — so returning every token in an org from one unauthenticated-by-default surface would make bulk disclosure the default. Rows carry isShared instead; fetch the single query when you actually need the link.

scheduleCount is how many schedules are attached, so a client can warn before deleting without a per-row round-trip.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
limit
integer
default: 200 >= 1 <= 200

Maximum saved queries to return.

cursor
string

Opaque continuation cursor returned by the preceding page.

Responses

Section titled “Responses”

200

Section titled “200”

Saved queries

Media typeapplication/json
object
savedQueries
required
Array
object
id
string format: uuid
userId
string format: uuid
name
string
sql

Public raw SQL. Null for structured definitions and all agent-scoped rows.

string
nullable
sqlPreview

Read-only structured preview, or protected scoped-SQL preview. Never submit this to reconstruct scope.

string
nullable
contentKind
string
Allowed values: sql definition
scopeKind
string
Allowed values: org agent
scopeAgentId
string format: uuid
nullable
sourceQueryId
string format: uuid
nullable
sqlDialect
string
nullable
Allowed values: postgres
description
string
nullable
shareToken

192-bit bearer capability granting unauthenticated read of this query’s results via /api/v1/share/sql/{token} — outside authentication and outside the BI feature flag. Never log it, never persist it outside your own secret store, and never include it in an agent transcript. Revoked via DELETE /api/v1/bi/saved-queries/{id}/share — a working route that, like this mint endpoint, is deliberately withheld from this contract rather than dashboard-only. Single-row responses only; the list route returns isShared instead.

string format: password
nullable
chartConfig
object
type
required
string
Allowed values: bar line pie
x
required
string
y
required
One of:
string
createdAt
string format: date-time
updatedAt
string format: date-time
isShared
required

Whether a share token exists. The token itself is never returned here.

boolean
scheduleCount
required

Number of schedules attached to this saved query.

integer
hasMore
required
boolean
nextCursor
required
string
nullable
Example
{
  "savedQueries": [
    {
      "contentKind": "sql",
      "scopeKind": "org",
      "sqlDialect": "postgres",
      "chartConfig": {
        "type": "bar"
      }
    }
  ]
}

400

Section titled “400”

The continuation cursor is malformed (invalid_cursor)

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: invalid_cursor
Example
{
  "error": {
    "code": "invalid_cursor"
  }
}

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