> ## Documentation Index
> Fetch the complete documentation index at: https://docs.dune.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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.
Minimum required API key scope: `Read`
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](/api-reference/executions/endpoint/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](/api-reference/pipelines/endpoint/get-pipeline-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
```bash theme={null}
# 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.
## OpenAPI
````yaml POST /v1/pipelines/execute
openapi: 3.0.1
info:
contact: {}
description: Dune API
title: DuneAPI
version: '1.0'
servers:
- url: https://api.dune.com/api
security: []
paths:
/v1/pipelines/execute:
post:
summary: Execute a pipeline
description: >-
Executes a specified pipeline. A pipeline allows you to chain multiple
queries and materialized view refreshes together and execute them as a
single unit.
parameters:
- description: API Key for the service
in: header
name: X-Dune-Api-Key
required: true
schema:
type: string
- description: Alternative to using the X-Dune-Api-Key header
in: query
name: api_key
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/models.ExecutePipelineRequest'
description: Pipeline execution request
required: true
x-originalParamName: body
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/models.ExecutePipelineResponse'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/models.Error400'
description: Bad Request
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/models.Error401'
description: Unauthorized
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/models.Error404'
description: Not Found
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/models.Error500'
description: Internal Server Error
components:
schemas:
models.ExecutePipelineRequest:
properties:
pipeline:
allOf:
- $ref: '#/components/schemas/models.Pipeline'
description: The pipeline definition containing nodes to execute
type: object
models.ExecutePipelineResponse:
properties:
pipeline_execution_id:
description: >-
Unique identifier for the pipeline execution. Use this ID to check
the status
and retrieve results of the pipeline execution.
example: 01HKZJ2683PHF9Q9PHHQ8FW4Q1
type: string
type: object
models.Error400:
properties:
error:
example: Bad Request
type: string
type: object
models.Error401:
properties:
error:
example: Invalid API Key
type: string
type: object
models.Error404:
properties:
error:
example: Object not found
type: string
type: object
models.Error500:
properties:
error:
example: Internal error
type: string
type: object
models.Pipeline:
properties:
nodes:
description: >-
List of nodes in the pipeline. Nodes are executed in dependency
order.
items:
$ref: '#/components/schemas/models.PipelineNode'
type: array
type: object
models.PipelineNode:
properties:
dependencies:
description: >-
List of node IDs that this node depends on. Nodes are executed in
dependency order.
items:
type: integer
type: array
id:
description: Unique identifier of the node in the pipeline
example: 1
type: integer
materialized_view_refresh:
allOf:
- $ref: '#/components/schemas/models.PipelineMaterializedViewRefreshNode'
description: >-
Materialized view refresh node configuration. Required if this node
refreshes a materialized view.
query_execution:
allOf:
- $ref: '#/components/schemas/models.PipelineQueryExecutionNode'
description: >-
Query execution node configuration. Required if this node executes a
query.
type: object
models.PipelineMaterializedViewRefreshNode:
properties:
name:
description: Name of the materialized view to refresh
example: mv_1
type: string
performance:
description: >-
The performance engine tier the refresh will be run on. Can be
`small`, `medium`, or `large`.
enum:
- small
- medium
- large
example: medium
type: string
type: object
models.PipelineQueryExecutionNode:
properties:
performance:
description: >-
The performance engine tier the execution will be run on. Can be
`small`, `medium`, or `large`.
enum:
- small
- medium
- large
example: medium
type: string
query_id:
description: Unique identifier of the query to execute
example: 1234
type: integer
query_parameters:
description: >-
SQL Query parameters in json key-value pairs. Each parameter is to
be provided in key-value pairs. This enables you to execute a
parameterized query with the provided values for your parameter
keys.
type: object
type: object
````