Celigo Storage query API reference

The Celigo Storage query API accepts one SQL statement and runs it against files in Celigo Storage as an asynchronous job: you submit the query, poll the job's status, and fetch the result one page at a time. This reference covers the three endpoints, their request and response fields, the limits that apply, and every error code. For a step-by-step walkthrough, see Query files in Celigo Storage.

Authentication and authorization

Send the token as a bearer token in the Authorization header. Celigo checks every file and folder the statement references against the token's access at submit:

• A Full access API token reads any file in the account's Celigo Storage.
• A Custom API token reads only files at or under the folders in its File storage paths. The reference itself must sit inside a granted folder — Celigo checks the reference, not the files it would expand to. A Custom token with no File storage paths can't reach Celigo Storage, and its submit request fails with 401 STORAGE_QUERY_ACCESS_REFUSED.
• A personal access token reads the files its user can open, under the user's role and integration access.

A path outside the token's scope and a path that doesn't exist return the identical 404 STORAGE_QUERY_SOURCE_NOT_FOUND, so the API never confirms or denies that an out-of-scope file exists. Jobs are private to the identity that submitted them — another identity's job returns 404 STORAGE_QUERY_JOB_NOT_FOUND.

Submit a query job

POST /v1/storage/query

• sql is required. One Celigo SQL statement, up to 16 KB. Multi-statement input is rejected. Other fields in the body are ignored; read options go inside the statement through reader functions. See Celigo storage query read options and format behavior.

The query API has no templating. Handlebars expressions aren't rendered — anything that isn't rendered before the request is sent reaches the API as literal text. Unquoted, it fails to parse at submit with 400 STORAGE_QUERY_INVALID_SQL; inside quotes, it passes the checks and either fails when the query runs or compares as text.

A successful submission returns 202 with the job's identifier:

{
  "jobId": "66e1f2a3b4c5d6e7f8a9b0c1",
  "status": "queued"
}

A 4xx response means Celigo rejected the statement, a path, or the token's access, and no job exists. The body carries an errors array:

{
  "errors": [
    { "code": "STORAGE_QUERY_SOURCE_NOT_FOUND", "message": "No storage file found at path \"/staging/orders/\"" }
  ]
}

Get a job's status

GET /v1/storage/query/{jobId}/status

The status field is one of queued, running, completed, or failed. A completed job reports the result's shape alongside its timing:

{
  "jobId": "66e1f2a3b4c5d6e7f8a9b0c1",
  "status": "completed",
  "createdAt": "2026-09-12T18:02:11.418Z",
  "startedAt": "2026-09-12T18:02:12.907Z",
  "completedAt": "2026-09-12T18:02:14.115Z",
  "executionMs": 1208,
  "rowCount": 4680,
  "truncated": false,
  "pageCount": 3,
  "columns": [
    { "name": "region", "type": "VARCHAR" },
    { "name": "orders", "type": "BIGINT" },
    { "name": "revenue", "type": "DOUBLE" }
  ]
}

A failed job reports the error instead of the result fields:

{
  "jobId": "66e1f2a3b4c5d6e7f8a9b0c1",
  "status": "failed",
  "createdAt": "2026-09-12T18:02:11.418Z",
  "startedAt": "2026-09-12T18:02:12.907Z",
  "completedAt": "2026-09-12T18:07:13.002Z",
  "error": {
    "code": "STORAGE_QUERY_TIMEOUT",
    "message": "Query exceeded the maximum execution time of 300 seconds"
  }
}

Fetch a result page

GET /v1/storage/query/{jobId}/results?page={n}

Results are always delivered in pages of roughly 5 MB, and a row is never split across pages. Page numbers start at 1. Request the next page while hasMore is true, up to pageCount.

{
  "page": 1,
  "pageCount": 3,
  "rowCount": 2000,
  "hasMore": true,
  "rows": [
    { "region": "NA", "orders": "1840", "revenue": 91230.5 },
    { "region": "EU", "orders": "1211", "revenue": 60117.25 }
  ]
}

A completed job with no rows returns page: 1, pageCount: 0, hasMore: false, and an empty rows array for page 1.

In the example, orders is a string and revenue is a number: Celigo returns 64-bit integers and decimals as strings so that large values keep every digit, and whole-number columns read from CSV and JSON files are typed as 64-bit integers. To receive a number, declare the column's type in the reader or cast the expression. See Celigo storage query read options and format behavior.

Job record retention

Celigo keeps each job's record and result pages for about 24 hours after the job finishes. After that, status and results requests return 404 STORAGE_QUERY_JOB_NOT_FOUND. Celigo doesn't keep the SQL text or the list of files a job read once the job has finished. There is no cancel request — a job runs until it completes, fails, or reaches the timeout.

Limits

Error codes

A rejected submission returns a 4xx with an errors array, and no job exists. A failure after submit surfaces as status: "failed" on the job with an error code and message. For symptom-based guidance, see Troubleshoot a Celigo Storage query job.

Request and statement errors

Function, generator, and reader errors

Source and path errors

Access and enablement errors

Status and results errors

Service errors

Job failure codes

These appear in the error field of a job with status: "failed", not as HTTP errors.

Learn more

• About querying Celigo Storage files
• Query files in Celigo Storage
• Query Celigo Storage from a flow with an async helper
• Troubleshoot a Celigo Storage query job
• Celigo Storage query SQL reference
• Celigo storage query read options and format behavior
• Celigo Storage overview
• Create an API token or Personal Access Token
• Restrict an API token to specific Celigo Storage paths