arcodash
Start free trial
PlatformConnectorsPricingSecurityDocs
Sign inStart free trial
api reference

Queries

List saved queries and trigger runs against them.

GET/api/queries

List queries visible to the current user, scoped by data-source access.

ParamTypeRequiredDescription
qstringNoFull-text search over query name and body.
tags[]string (repeated)NoFilter to queries containing all of the given tags.
filterstringNo"all" (default), "by-me", or "shared-with-me".
include_archivedbooleanNoInclude archived queries. Defaults to false.

Response

{
  "queries": [
    {
      "id": 42,
      "name": "Weekly signups",
      "data_source_id": 3,
      "is_archived": false,
      "tags": ["growth"],
      "updated_at": "2026-07-10T09:00:00Z"
    }
  ]
}

POST/api/queries/{id}/run

Manually run the query through the runs pipeline. Returns 201 if a new run was started, 200 if one was already in flight.

Response

{
  "id": 7781,
  "status": "started",
  "triggered_by": "user",
  "scheduled_for": null,
  "started_at": "2026-07-17T12:00:00Z",
  "finished_at": null,
  "duration_ms": null,
  "row_count": null,
  "query_result_id": null,
  "error": null
}

POST/api/queries/{id}/refresh

Ad-hoc cache-or-enqueue: returns an immediate cached result or an enqueued job. See the async query model.

Response

// EITHER an immediate result:
{ "query_result": { "id": 501, "data": { "...": "..." }, "runtime": 0.42 } }

// OR an enqueued job:
{ "job": { "id": 9001, "status": 1, "query_result_id": null } }

POST/api/queries/{id}/results

Execute the saved query (same cache-or-enqueue outcome as refresh), running the published version once the query has been published, otherwise the draft. Parameter definitions live on the saved query itself — pass only runtime values.

ParamTypeRequiredDescription
parametersobjectNoRuntime values for the query's parameters, keyed by parameter name.
max_ageintegerNoForce a fresh run instead of serving a cached result older than this many seconds.

Request

{ "parameters": { "since": "2026-07-01" } }

Response

// EITHER an immediate result:
{ "query_result": { "id": 501, "data": { "...": "..." }, "runtime": 0.42 } }

// OR an enqueued job:
{ "job": { "id": 9001, "status": 1, "query_result_id": null } }