---
title: "Execute Published Pipeline"
method: POST
path: "/v1/projects/{projectId}/pipeline-executions"
tags: ["Pipeline Execution"]
---

# Execute Published Pipeline

`POST /v1/projects/{projectId}/pipeline-executions`

## Request

- Base URL: `https://eu1.api.matillion.com/dpc`
- URL: `https://eu1.api.matillion.com/dpc/v1/projects/{projectId}/pipeline-executions`
- Auth: HTTP bearer

Triggers the asynchronous execution of a named, published pipeline within the specified project.

The pipeline must be published to the target environment before it can be executed. On success, returns a `pipelineExecutionId` that can be used to track or query the execution status.

**Key behaviours:**
* By default, the latest published version of the pipeline is executed. Use `versionName` to target a specific artifact version.
* If no `agentId` is provided, the default agent configured for the target environment is used.
* Use `executionTag` to control concurrency — only one execution per tag is permitted to run at a time within a given environment. A `409 Conflict` is returned if an execution with the same tag is already in progress.
* Runtime variable values can be overridden per-execution using `scalarVariables` (key-value pairs) or `gridVariables` (two-dimensional string arrays), without modifying the published pipeline definition.
* A `410 Gone` is returned if the pipeline has been disabled.

## Path parameters

- `projectId` string, uuid, required

## Request body

- PipelineExecutionRequest
  - `agentId` string: Optional agentId to execute the pipeline. If not specified the default agent for the provided environment will be used
  - `environmentName` string, required: Environment pipeline is published to
  - `executionTag` string: Optional execution tag, this allows control of pipeline execution concurrency. Only 1 pipeline execution is allowed to run per execution tag in a given environment.
  - `gridVariables` object: Optional map of grid variable names to two-dimensional string arrays, used to override grid variable values for this execution without modifying the published pipeline definition
  - `pipelineName` string, required: Name of the pipeline to execute
  - `scalarVariables` object: Optional map of scalar variable names to their override values for this execution, without modifying the published pipeline definition
  - `versionName` string: Optional artifact version name of the pipeline to execute. If not specified the latest version will be executed

## Response `201`

Pipeline executed

- PipelineExecutionResponse
  - `pipelineExecutionId` string, uuid: Identifier of executing pipeline

## Other responses

- `400`: Invalid request
- `401`: Unauthorized
- `403`: Forbidden
- `404`: Pipelines not Found
- `409`: Conflict, concurrent pipeline running for execution tag
- `410`: Pipeline has been disabled
- `500`: Unexpected error occurred
- `504`: Gateway timeout

---

[API](https://skmtc.dev/maia/apis/maia-public-rest-api.md) - [All operations](https://skmtc.dev/maia/apis/maia-public-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/maia/apis/maia-public-rest-api/revisions/6239825f68eb?raw)