Query

Run a data query

Returns up to limit rows for the requested fields over the requested date range. Supports filters, settings and period-over-period comparison via compare_to. Pagination is via cursor. Cursors are bound to the exact query+account; mutating any input invalidates the cursor and the response is treated as a fresh first page. Numeric values that cannot be computed (for example a ratio with a zero denominator) are returned as null. An error with error_code: PROVIDER_UNAVAILABLE means the platform behind the data source is throttling requests or failing temporarily: it is not an error of the client, and the same request should be retried later.

post/query

Request

  • Base URL: https://api.reportingninja.com/v1
  • URL: https://api.reportingninja.com/v1/query
  • 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

Changes

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