Trigger a Data Flow and Check Status with APIs

Pigment’s generic API lets you automate Data Flow runs. This article explains how to trigger a Data Flow and check its status using the Pigment Data Flow API.

Before you begin

To use the Pigment Data Flow API, you’ll need the following information:

• Pigment API Key. This private key will be used to authenticate the service calling the API. To generate the key, go to Workspace settings and select API Keys. You need the Data Flows scope for all endpoints in this page. For more information, see Manage API Keys.

• Data Flow ID. This ID represents the Data Flow configuration you want to trigger. For more information, see List Data Flows to retrieve it.

ℹ️ Note

A Data Flow groups one or more Data Actions (Metric-to-Metric or List-to-List imports) into a single configuration, executed either in Parallel or Sequentially. For more information, see Create and manage Data Flows.

Access and permissions

An API key inherits the permissions of the user who created it. For a Data Flow to run successfully, that user must be authorized to execute every Data Action included in the flow. For more information, see Manage API Keys.

Pigment applies the same permission checks whether the Data Flow is launched through the API or from a Board.

⚠️ Important

You need an API key with the Data Flows scope for all API endpoints below.

Swagger / OpenAPI specification

Pigment has a Swagger page with all the publicly available API endpoints: https://pigment.app/api/swagger.

You can find the Data Flow API endpoints under DataFlowV1.

List Data Flows

Use the following GET endpoint to list the Data Flows configured in an application. The response includes the Data Flow id required to start an execution:

https://pigment.app/api/v1/dataFlows?applicationId={APPLICATION_ID}

Replace {APPLICATION_ID} with the ID of the application that contains the Data Flows.

API response

[
  {
    "id": "33d0d7d0-6125-47c4-b36a-882f4ed53b33",
    "name": "Monthly Headcount Sync",
    "description": "Syncs actuals from HR to FP&A",
    "executionMode": "Sequential",
    "applicationId": "app-xxxx",
    "steps": [
      { "stepIndex": 0, "importConfigurationId": "cfg-aaa" },
      { "stepIndex": 1, "importConfigurationId": "cfg-bbb" }
    ]
  }
]

Example

cURL example:

# Variables
export PIGMENT_API_KEY="CHANGE ME"
export APPLICATION_ID="CHANGE ME"

# List Data Flows
curl -X GET "https://pigment.app/api/v1/dataFlows?applicationId=${APPLICATION_ID}" \
-H "Authorization: Bearer ${PIGMENT_API_KEY}"

Trigger a Data Flow

Use this POST endpoint to trigger a Data Flow:

https://pigment.app/api/v1/dataFlow/trigger?dataFlowId={DATA_FLOW_ID}

Request configuration

• Replace {DATA_FLOW_ID} with the id retrieved from the List Data Flows endpoint above.

• To authenticate the API call, add an HTTP Authorization header to your request: Authorization: Bearer {API_KEY}

• Replace {API_KEY} by the key retrieved in Before you begin.

• No request body is required.

Your final configuration should look like this:

Authorization: Bearer M2pwMmUyMzItOTg3NS00MmY0LTlmY2YtNjNmZTJjZTU2OGpw

⚠️ Important

If your Data Flow contains P2P Data Actions that use Selective mapping based on a Data Action Parameter, triggering the Data Flow will fail.

API Response

A successful request returns a dataFlowExecutionId, which you can use to check the execution status.

{
  "dataFlowExecutionId": "a1b2c3d4-0000-0000-0000-e5f6a7b8c9d0"
}

If the same Data Flow is already running, the API returns a 409 Conflict instead:

{
  "error": "DataFlowAlreadyRunning",
  "dataFlowExecutionId": "a1b2c3d4-0000-0000-0000-e5f6a7b8c9d0"
}

Use the returned dataFlowExecutionId to monitor the current execution rather than starting the Data Flow again.

Example

cURL example:

# Variables
export PIGMENT_API_KEY="CHANGE ME"
export DATA_FLOW_ID="CHANGE ME"

# Trigger the Data Flow
curl -X POST "https://pigment.app/api/v1/dataFlow/trigger?dataFlowId=${DATA_FLOW_ID}" \
-H "Authorization: Bearer ${PIGMENT_API_KEY}"

Data Flow execution status

Use this GET endpoint to retrieve a Data Flow execution status:

https://pigment.app/api/v1/dataFlow/{DATA_FLOW_EXECUTION_ID}/status

Replace {DATA_FLOW_EXECUTION_ID} by the ID returned by the trigger call described above.

Your final configuration should look like this:

API response

{
  "dataFlowExecutionId": "a1b2c3d4-0000-0000-0000-e5f6a7b8c9d0",
  "id": "33d0d7d0-6125-47c4-b36a-882f4ed53b33",
  "executionMode": "Sequential",
  "status": "InProgress",
  "createdAt": "2026-05-13T10:00:00.000Z",
  "completedAt": null,
  "steps": [
    {
      "stepIndex": 0,
      "importConfigurationId": "cfg-aaa",
      "status": "Completed",
      "importId": "f2b03cab-ba63-4525-bd59-c597f6721973"
    },
    {
      "stepIndex": 1,
      "importConfigurationId": "cfg-bbb",
      "status": "InProgress",
      "importId": "91c4d2ea-1234-5678-abcd-ef0123456789"
    }
  ],
  "errorsDetails": []
}

The top-level status can have four values:

Each entry in steps has its own status, which can be Pending, InProgress, Completed, Failed, or Skipped.

Use a step’s importId with the existing Import status API to retrieve its detailed report:

GET /api/v1/import/{IMPORT_ID}/status?includedDetailedReport=true

The name and description fields within errorsDetails provide additional information about an error. They are populated only when the execution has a Failed or PartialFailure status.

Example

cURL example:

# Variables
export PIGMENT_API_KEY="CHANGE ME"
export DATA_FLOW_EXECUTION_ID="CHANGE ME"

# Get status
curl -X GET "https://pigment.app/api/v1/dataFlow/${DATA_FLOW_EXECUTION_ID}/status" \
-H "Authorization: Bearer ${PIGMENT_API_KEY}"

Troubleshoot failed Data Flow executions

You can review Data Flow executions from the application’s History page as well as through the status API. Go to All Actions then Data Flows. For more information, see View Data Flow History.

If a step fails, use its importId to retrieve the corresponding import’s detailed report. The report can help you determine whether the issue comes from the source data or the saved Import configuration.