Query

Submit an async query

Validates the input identically to /v1/query. On success persists the query as a background job and returns a job_id immediately. The query is processed asynchronously; poll /v1/query/status to retrieve the result. Successful results are retained for 8 hours after completion. Authorization: Bearer token (same as other endpoints).

post/query/async

Request

  • Base URL: https://api.reportingninja.com/v1
  • URL: https://api.reportingninja.com/v1/query/async
  • Auth: HTTP bearer

Request body

integration_idstring required
connection_keystring required
account_idstring required
data_viewstring
fieldsstring[] required
comparison_type'percentage' | 'absolute' | 'value'
settingsobject

Per-request settings. Validated strictly per integration: only keys declared in /v1/integrations/detail are accepted, and any other key answers HTTP 200 with error_code UNKNOWN_PARAM. Each setting that applies (per its applies_to_data_views) is REQUIRED and is not filled in for you; a missing one answers HTTP 200 with error_code MISSING_REQUIRED_FIELD. See the Setting schema and the catalog of each integration.

limitinteger required

How many rows to bring back. A value of zero or less is refused with INVALID_LIMIT. A larger value is capped at 50000 instead of being refused.

cursorstring nullable

Opaque cursor returned by a previous response as meta.next_cursor. Submit verbatim to continue pagination. Cursors expire 3 hours after the original query; an expired cursor answers CURSOR_EXPIRED. An unreadable cursor (different query or account) is silently ignored and pagination restarts from page 1. For async queries the same 3-hour expiration applies, even if the job result is still available.

bypass_cacheboolean

If true, the API skips the cache lookup and always re-executes the query against the upstream platform. The fresh result is still written to the cache (so subsequent queries with the same input benefit). Useful when the client needs guaranteed-fresh data. Applies to both /v1/query (sync) and /v1/query/async.

Response

The answer of the call, or a business error envelope. This endpoint reports its own errors with HTTP 200 and status=error: read envelope.status before reading data.

OR

Example response

{
  "data": {
    "job_id": "1234567890"
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.