Skip to main content

List Pipelines

List document processing pipeline runs via GET /v1/pipelines: cursor-paginated, newest first, filterable by status or schema_id. Preview runs are excluded.

GET /v1/pipelines lists your document processing pipeline runs, cursor-paginated and ordered newest first by default. Each entry is a slim summary of a run: its id, name, status, the Spec it ran against, and the compiled phase count. Preview runs (the sample-anchored runs the app uses to render Spec previews) are excluded, so this listing only shows real pipeline runs.

Filter the listing with status to narrow to runs in a particular lifecycle state, or schema_id to scope to one Spec. Combine them to find, for example, every active run of a given Spec. Pagination is cursor-based: pass the next_cursor from the previous response as cursor to walk the result set deterministically across pages.

The listing is intentionally lean. For a run's phase progress use GET /v1/pipelines/{id}/progress, and for its full detail use GET /v1/pipelines/{id}. Each list entry carries a links object with self, progress, and a dashboard URL into the app. This endpoint requires an API key with the read scope.

The status values you will see are active, paused, finalizing, completed, and archived. Statuses are stored, not folded, so a status filter matches exactly one lifecycle state — filter on active for in-flight work, but remember that a run in finalizing is neither active nor completed; check for it explicitly when you gate downstream automation on the listing.

Preview runs are excluded from this listing but are still served by GET /v1/pipelines/{id}/results — a preview has a real record set. Do not infer from absence here that a pipeline id is invalid; fetch it directly.
GET/v1/pipelines

Query parameters

statusstringFilter by pipeline status: active, paused, finalizing, completed, or archived. Exact match on one state.
schema_idstringFilter to runs of a single Spec (user_schema UUID).
limitintegerMaximum number of results to return. Default: 20
cursorstringPagination cursor from a previous response.
orderstringSort direction by created_at: asc or desc. Default: desc

Request

curl "https://api.talonic.com/v1/pipelines?status=active&schema_id=sch_uuid_1" \
  -H "Authorization: Bearer $TALONIC_API_KEY"

Response

Response fields

dataarrayArray of pipeline run objects.
data[].idstringPipeline run UUID.
data[].namestringRun name.
data[].statusstringPipeline status.
data[].schemaobjectThe Spec used for the run: { id }.
data[].phase_countintegerNumber of compiled phases in the run's phase config.
data[].created_atstringISO 8601 creation timestamp.
data[].linksobjectRelated resource URLs (self, progress, dashboard).
pagination.totalintegerTotal number of runs matching the query.
pagination.limitintegerMaximum results per page.
pagination.has_morebooleanWhether more results exist beyond this page.
pagination.next_cursorstring | nullCursor to fetch the next page. Null if no more results.

Response

{
  "data": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "name": "Lease Agreement — 2024-09-14",
      "status": "active",
      "schema": { "id": "sch_uuid_1" },
      "phase_count": 5,
      "created_at": "2024-09-14T10:32:00.000Z",
      "links": {
        "self": "/v1/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "progress": "/v1/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890/progress",
        "dashboard": "https://app.talonic.com/pipelines/a1b2c3d4-e5f6-7890-abcd-ef1234567890"
      }
    }
  ],
  "pagination": {
    "total": 12,
    "limit": 20,
    "has_more": false,
    "next_cursor": null
  }
}

Errors

Error responses

401unauthorizedMissing or invalid API key.
429rate_limitedToo many requests. Retry after the period indicated in the Retry-After header.

Frequently asked questions

Why don't my preview runs appear?+
Preview runs are sample-anchored runs the app uses to render Spec previews. They never produce delivered output and are excluded from this listing. Only real pipeline runs are returned.
How does cursor pagination work here?+
Pass the `next_cursor` value from the previous response as the `cursor` query parameter to fetch the next page. When `has_more` is `false`, you have reached the last page.
Can I combine the status and schema_id filters?+
Yes. The filters compose, so `status=active&schema_id=<uuid>` returns every currently active run of one Spec. This is the quickest way to check whether a Spec already has a run in flight before launching another.
How do I find the pipeline behind a /v1/run call?+
Do not scan this listing — poll GET /v1/run/{id} instead: once ingestion finishes, its response carries the compiled pipeline_id directly. The listing is for browsing runs by Spec or lifecycle state, not for correlating submissions.

Related

Run Pipeline
Get Pipeline
Pipeline Progress