Execute Pipeline

Executes a specified pipeline. A pipeline allows you to chain multiple queries and materialized view refreshes together and execute them as a single unit.

POST /v1/pipelines/execute

Execute a pipeline

cURL

curl --request POST \
  --url https://api.dune.com/api/v1/pipelines/execute \
  --header 'Content-Type: application/json' \
  --header 'X-Dune-Api-Key: <x-dune-api-key>' \
  --data '
{
  "pipeline": {
    "nodes": [
      {
        "dependencies": [
          123
        ],
        "id": 1,
        "materialized_view_refresh": {
          "name": "mv_1",
          "performance": "medium"
        },
        "query_execution": {
          "performance": "medium",
          "query_id": 1234,
          "query_parameters": {}
        }
      }
    ]
  }
}
'

200

{
  "pipeline_execution_id": "01HKZJ2683PHF9Q9PHHQ8FW4Q1"
}

This endpoint builds an execution pipeline from a specified query and executes it. The pipeline will automatically include all materialized views in the query’s lineage, ensuring coordinated execution of dependent queries.

How It Works

When you execute a pipeline using this endpoint:

1. Lineage Detection: Dune analyzes the query to identify all materialized views it depends on
2. Pipeline Construction: A pipeline is automatically built that includes all dependencies in the correct order
3. Coordinated Execution: All queries and materialized view refreshes are executed as a single unit
4. Status Tracking: Returns a pipeline_execution_id for monitoring progress

Key Differences from Query Pipeline Execute

This endpoint differs from the Execute Query Pipeline endpoint:

Feature	Execute Pipeline	Execute Query Pipeline
Endpoint	POST /v1/pipelines/execute	POST /v1/query/{query_id}/pipeline/execute
Query ID	In request body	In URL path
Lineage	Automatically includes all materialized views	Executes predefined pipeline
Use Case	Dynamic pipeline based on query dependencies	Predefined pipeline execution

Request Body

The request body accepts:

• query_id (required): The unique identifier of the query to execute
• performance (optional): Execution tier - medium (default) or large
• query_parameters (optional): SQL query parameters as JSON key-value pairs

Use Cases

This endpoint is ideal for:

• Dependency Management: Automatically refreshing all materialized views a query depends on
• Consistent Updates: Ensuring all dependent data is fresh before query execution
• Dynamic Pipelines: When you want to execute based on runtime query dependencies
• Simplified Workflow: No need to manually define pipeline structure

Monitoring Pipeline Execution

After executing the pipeline:

1. Save the returned pipeline_execution_id
2. Use the Get Pipeline Execution Status endpoint to monitor progress
3. Track the status of each materialized view refresh and query execution
4. Retrieve results once the pipeline completes

Example Workflow

# 1. Execute pipeline for query ID 1234567
curl -X POST "https://api.dune.com/api/v1/pipelines/execute" \
  -H "X-Dune-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query_id": 1234567,
    "performance": "medium",
    "query_parameters": {
      "start_date": "2024-01-01",
      "end_date": "2024-12-31"
    }
  }'

# Response: { "pipeline_execution_id": "01HZABC123..." }

# 2. Check pipeline status
curl "https://api.dune.com/api/v1/pipelines/executions/01HZABC123.../status" \
  -H "X-Dune-Api-Key: YOUR_API_KEY"

This endpoint automatically determines which materialized views need to be refreshed based on the query’s lineage. You don’t need to manually specify dependencies.

Performance Considerations

• Medium tier: Best for most queries with standard dependencies
• Large tier: Use for complex queries with many dependencies or large materialized views
• Credits are consumed based on actual compute resources used for each node in the pipeline

If your query depends on multiple materialized views, this endpoint will refresh all of them in the correct order before executing your query, ensuring data consistency.

Headers

X-Dune-Api-Key · string · required

API Key for the service

Query Parameters

api_key · string

Alternative to using the X-Dune-Api-Key header

Body

application/json

Pipeline execution request

pipeline · object

The pipeline definition containing nodes to execute

Show child attributes

Response

200

application/json

OK

pipeline_execution_id · string

Unique identifier for the pipeline execution. Use this ID to check the status and retrieve results of the pipeline execution.

Example:

"01HKZJ2683PHF9Q9PHHQ8FW4Q1"