Skip to content
justcrawl.io

Create a saved query

POST
/api/v1/bi/saved-queries
Code sample: cURL
curl -X POST 'https://api.justcrawl.io/api/v1/bi/saved-queries' \
  -H 'Authorization: Bearer $JUSTCRAWL_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{"name":"Daily status mix","sql":"SELECT status, count(*) FROM jobs GROUP BY 1"}'

Persist a query under a name. Names are unique per organization; a collision returns 409 saved_query_name_taken. A malformed chartConfig returns 422 rather than 400, so a broken chart picker payload is distinguishable from a missing query source.

Supply exactly one of literal sql or a completed owned sourceQueryId. Source-based saving copies the server-owned definition and immutable execution scope.

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
One of:
object
name
required
string
<= 120 characters
sql
required
string
<= 100000 characters
description
string
nullable <= 1000 characters
chartConfig
object
type
required
string
Allowed values: bar line pie
x
required
string
y
required
One of:
string

Responses

Section titled “Responses”

201

Section titled “201”

Created

Media typeapplication/json
object
savedQuery
required

A saved BI query. Returned by the single-row routes (get, create, patch, and the share mint/revoke pair). List rows drop shareToken and add isShared plus scheduleCount instead.

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
Example
{
  "savedQuery": {
    "contentKind": "sql",
    "scopeKind": "org",
    "sqlDialect": "postgres",
    "chartConfig": {
      "type": "bar"
    }
  }
}

400

Section titled “400”

Body rejected (invalid_name, invalid_sql, invalid_description, invalid_saved_query_input, invalid_source_query)

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_name invalid_sql invalid_description invalid_saved_query_input invalid_source_query
Example
{
  "error": {
    "code": "invalid_name"
  }
}

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

404

Section titled “404”

The source query was not found in this organization (not_found)

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

409

Section titled “409”

A saved query with that name exists (saved_query_name_taken), or the source is not a completed scope-proven execution (source_query_not_executable)

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

422

Section titled “422”

The chartConfig field is present but malformed (invalid_chart_config)

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

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