---
title: "Get task data or status"
method: GET
path: "/external/v1/tasks/{task_id}"
tags: ["Task"]
---

# Get task data or status

`GET /external/v1/tasks/{task_id}`

## Request

- Base URL: `https://api.databar.ai` (the document declares no server; this is the origin it was published from)
- URL: `https://api.databar.ai/external/v1/tasks/{task_id}`
- Auth: API key in header `x-apikey`

``include_partial``: while a bulk run is still going, return the rows that have
already finished. Off by default — it turns every poll into a full read of the
result hash, which a client polling every few minutes pays for and rarely wants.

``include_trace``: for a flow task, also return what each step of the run did —
which node ran, what it produced, why it stopped, what it cost. Off by default, so
the response is unchanged for callers that don't ask. Use it when a run comes back
``completed`` with nothing in ``data``: the trace says whether every step missed,
a condition halted the run, or a provider errored. Other task types return no
``trace``. For a bulk flow task ``trace`` is a list aligned to the inputs, like
``data`` — a list or nothing, never a single run.

Results expire after 24 hours and the poll then answers 410. The record of the
run is kept, though, so with ``include_trace`` that 410 still carries the trace.

## Path parameters

- `task_id` string, required

## Query parameters

- `include_partial` boolean
- `include_trace` boolean

## Response `200`

OK

- TaskDetailOut
  - `task_id` string, required: Unique identifier of the task.
  - `request_id` string, nullable: Deprecated: use task_id instead. Same value as task_id.
  - `status` string, required: Current status: 'processing', 'completed', 'failed', or 'cancelled'.
  - `progress` object, nullable: How far a bulk run has got: `total`, `completed`, `no_data`, `failed` and `processing` counts of inputs. `no_data` is a clean miss. `failed` is a real error on that input. Omitted for single (non-bulk) runs.
  - `data` union: Resulting data once completed. For bulk runs this is an array aligned to the inputs: one element per input, in the same order they were submitted, with null for inputs that returned no data (len(data) equals the number of inputs, and data[i] is the result for input i). A single (non-bulk) run returns the result object directly.
    - unknown[]
      - unknown
    - object
  - `input` object, nullable: Echo of the submitted inputs, aligned to `data` so you can attribute results back to what was searched. Shape mirrors the run body: {"params": {...}} for a single run and {"params": [{...}, ...]} for a bulk run, where params[i] corresponds to data[i] (same order, misses included). Omitted for waterfall tasks and for flow tasks whose input echo has expired.
  - `error` union: Why the task returned no data. A clean miss reads "No matching data found for this input." — for waterfalls followed by the providers that were tried. A bulk run returns one message per input, in input order.
    - string[]
    - string
  - `credits_spent` number
  - `trace` union: Per-step account of a flow run, returned only when the request asks for it with `include_trace=true`. Shaped like `data`: one object for a single run, and for a bulk run a list aligned to the inputs, where trace[i] is the run for input i (null if no run can be attributed to that input). A bulk trace is always a list, never a single object. Omitted for enrichment and waterfall tasks, which have no steps to report, and for bulk runs started before per-input traces were recorded, whose runs can't be matched to their inputs.
    - RunTraceOut: What a flow run actually did, step by step. Returned on ``include_trace=true``.
      - `run_id` integer, nullable: Id of the recorded run. Null for a trace recovered from the short-lived cache.
      - `flow_version` integer, nullable: Version of the flow graph this run executed, so a stretch of empty results can be tied to the edit that started it.
      - `run_status` string: The run's own verdict: 'completed', 'no_data', 'aborted', 'failed' or 'running'. Finer-grained than the task `status`, which only distinguishes completed from failed: a run where every step returned nothing reports task status 'completed' and run_status 'no_data'.
      - `termination_reason` string: Machine-readable code for why the run stopped short, e.g. 'no_data' or 'condition_not_met'. Empty when nothing halted it.
      - `error_message` string: Human-readable form of `termination_reason`.
      - `started_at` string, date-time, nullable
      - `finished_at` string, date-time, nullable
      - `duration_seconds` number, nullable
      - `total_cost` string, nullable: Credits the run's steps summed to.
      - `steps` object[]: One entry per node the graph executed, in execution order: `node_id`, `type` ('enrichment', 'transform', 'condition', 'skipped', 'failed'), `result`, `details` and `cost`. A node pruned by a condition appears as type 'skipped'. Provider response bodies are not included — those come back in `data`.
    - RunTraceOut[]
      - `run_id` integer, nullable: Id of the recorded run. Null for a trace recovered from the short-lived cache.
      - `flow_version` integer, nullable: Version of the flow graph this run executed, so a stretch of empty results can be tied to the edit that started it.
      - `run_status` string: The run's own verdict: 'completed', 'no_data', 'aborted', 'failed' or 'running'. Finer-grained than the task `status`, which only distinguishes completed from failed: a run where every step returned nothing reports task status 'completed' and run_status 'no_data'.
      - `termination_reason` string: Machine-readable code for why the run stopped short, e.g. 'no_data' or 'condition_not_met'. Empty when nothing halted it.
      - `error_message` string: Human-readable form of `termination_reason`.
      - `started_at` string, date-time, nullable
      - `finished_at` string, date-time, nullable
      - `duration_seconds` number, nullable
      - `total_cost` string, nullable: Credits the run's steps summed to.
      - `steps` object[]: One entry per node the graph executed, in execution order: `node_id`, `type` ('enrichment', 'transform', 'condition', 'skipped', 'failed'), `result`, `details` and `cost`. A node pruned by a condition appears as type 'skipped'. Provider response bodies are not included — those come back in `data`.

## Other responses

- `410`: Gone

---

[API](https://skmtc.dev/databar/apis/external-api.md) - [All operations](https://skmtc.dev/databar/apis/external-api/llms.txt) - [OpenAPI document](https://skmtc.dev/databar/apis/external-api/revisions/efe15f8bb9bb?raw)