Ataccama ONE Agentic ONE Desktop ONE DQ&C ONE MDM ONE RDM ONE Runtime Server
Downloads

Processing API

The REST API is currently in Early Access Preview. The API specification and endpoints might change before being marked as stable.

We recommend testing thoroughly and being prepared to adapt to potential changes in future releases.

This guide shows you how to track the asynchronous work that other APIs start. You can poll a processing workflow until it completes, find runs across your environment, cancel a running workflow, and diagnose a failed one from its jobs.

Before using the Processing API, configure authentication as described in API Authentication.

API base URL

All Processing API endpoints are accessed through the following base URL:

https://{your-environment}.ataccama.one/api/processing/v1

Replace {your-environment} with your environment identifier from the Ataccama Cloud Portal.

When to use this API

Use the Processing API when you need to:

  • Poll a run: Track a workflow that another API started, for example a DQ evaluation triggered from a pipeline.

  • Find runs: List the processing workflows in your environment and filter them by status, type, or name.

  • Cancel a run: Stop a running workflow, for example one started with the wrong configuration.

  • Diagnose failures: Find out which job caused a workflow to fail, and why.

Workflows and jobs

A processing workflow is one asynchronous run. It consists of jobs, the units of work that run within it. Both workflows and jobs have their own URNs (see URN Reference), and both report a status, with values such as PENDING, RUNNING, FINISHED, FAILED, CANCELED, and SKIPPED.

The Processing API tracks and cancels the jobs but doesn’t start them. You start jobs through the other APIs. For example, starting a DQ monitor processing returns a polling.href link that points to a workflow in this API.

Get a workflow

Retrieve the state of a specific workflow, typically to poll a processing until it completes.

Request: Retrieve a processing workflow
curl -X GET "https://{your-environment}.ataccama.one/api/processing/v1/workflows/{workflowUrn}" \
  -H "Authorization: Bearer {access_token}"
Response: Retrieved workflow
{
    "urn": "urn:ata:{your-tenant}:processing:workflow:f783ee2b-b990-4ee1-aef7-53186433fe54",
    "type": "DQ-JOB",
    "startedAt": "2026-07-15T08:24:21Z",
    "status": "FINISHED",
    "name": "CUSTOMERS / Primary Monitor",
    "owner": "jane.doe",
    "finishedAt": "2026-07-15T08:26:07Z",
    "duration": 106,
    "errors": []
}

While status is PENDING or RUNNING, the response includes a Retry-After header with the number of seconds to wait before polling again.

A failed workflow lists its failures in errors. Each entry carries the URN of the failed job and a reason.

For polling a DQ evaluation, including what each status value means for your pipeline, see Run DQ evaluation from pipelines.

List workflows

List the processing workflows in your environment.

Request: List failed workflows
curl -X GET "https://{your-environment}.ataccama.one/api/processing/v1/workflows?status=FAILED&size=20" \
  -H "Authorization: Bearer {access_token}"
Request: List running DQ processings
curl -X GET "https://{your-environment}.ataccama.one/api/processing/v1/workflows?status=RUNNING&type=DQ-JOB" \
  -H "Authorization: Bearer {access_token}"
Query parameters
Parameter Type Required Description

status

string

No

Filter by workflow status (for example, RUNNING or FAILED).

type

string

No

Filter by workflow type (for example, DQ-JOB).

name

string

No

Filter by workflow name (for example, CUSTOMERS / Primary Monitor).

size

integer

No

Number of workflows to return per page.

Default: 20. Max: 100.

sort

string

No

Comma-separated field names for sorting. Prefix with a hyphen (-) for descending order.

Default: -startedAt.

after

string

No

Cursor for forward pagination. Use the value from meta.next in the previous response.

before

string

No

Cursor for backward pagination. Use the value from meta.prev in the previous response.

The response contains a data array with up to size workflows, and a meta object with the prev and next pagination cursors. A cursor is null when there are no further pages in that direction.

Cancel workflows

Cancel one or more running workflows. Identify each workflow by its URN, which you find in the urn field of a Get a workflow or List workflows response.

Request: Cancel two workflows
curl -X POST "https://{your-environment}.ataccama.one/api/processing/v1/workflows/cancel" \
  -H "Authorization: Bearer {access_token}" \
  -H "Content-Type: application/json" \
  -d '{
    "workflows": [
      "urn:ata:{your-tenant}:processing:workflow:f783ee2b-b990-4ee1-aef7-53186433fe54",
      "urn:ata:{your-tenant}:processing:workflow:db41cc48-47b3-3707-8eac-e471885f9315"
    ]
  }'
Response: Per-workflow cancellation outcome
{
  "workflows": [
    {
      "urn": "urn:ata:{your-tenant}:processing:workflow:f783ee2b-b990-4ee1-aef7-53186433fe54",
      "cancelled": true
    },
    {
      "urn": "urn:ata:{your-tenant}:processing:workflow:db41cc48-47b3-3707-8eac-e471885f9315",
      "cancelled": false
    }
  ]
}

The response reports each workflow separately. The cancelled field states whether the workflow was canceled.

List jobs

List the jobs of a workflow, typically to find the failed one.

Request: List the jobs of a workflow
curl -X GET "https://{your-environment}.ataccama.one/api/processing/v1/jobs?workflow={workflowUrn}" \
  -H "Authorization: Bearer {access_token}"
Query parameters
Parameter Type Required Description

workflow

string

No

Restricts the result to the jobs of the given workflow. Omit to list jobs across all workflows.

status

string

No

Filter by job status (for example, FAILED).

type

string

No

Filter by job type.

name

string

No

Filter by job name.

size

integer

No

Number of jobs to return per page.

Default: 20.

Max: 100.

sort

string

No

Comma-separated field names for sorting. Prefix with a hyphen (-) for descending order.

Default: -submittedAt.

after

string

No

Cursor for forward pagination. Use the value from meta.next in the previous response.

before

string

No

Cursor for backward pagination. Use the value from meta.prev in the previous response.

The response is paginated in the same way as List workflows.

Get a job

Retrieve a specific job, typically to read the error of a failed one.

Request: Retrieve a processing job
curl -X GET "https://{your-environment}.ataccama.one/api/processing/v1/jobs/{jobUrn}" \
  -H "Authorization: Bearer {access_token}"

Each job reports its status, the submittedAt, startedAt, and finishedAt timestamps, and, for a failed job, an error object with the failure reason.

Error handling

The API returns standard HTTP status codes and problem details for errors:

Status code Description

200 OK

Request successful.

401 Unauthorized

Invalid or expired access token.

403 Forbidden

Insufficient permissions to access the requested resource.

404 Not Found

Workflow or job does not exist.

API reference

For detailed API reference, including all endpoints, parameters, request and response schemas, and examples, see Processing API specification.

Next steps

Was this page useful?