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

# Execute Published Pipeline

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

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.net/maia/apis/maia-public-rest-api.md) · [All operations](https://skmtc.net/maia/apis/maia-public-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/maia/maia-public-rest-api/versions/6239825f68eb/schema)