> ## Documentation Index
> Fetch the complete documentation index at: https://docs.maia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Executing and managing a pipeline

export const m_runner = "Maia runner";

export const designer = "Designer";

export const maia = "Maia";

In this guide, you will learn how to execute a published pipeline, check its status, and terminate a running pipeline using the Maia API. Additionally, you'll discover how to obtain the necessary Project ID and Environment Name for pipeline execution.

To execute and manage a pipeline using the API, the pipeline *must* be published. Unpublished pipelines cannot be executed or managed using the API. To publish a pipeline, perform the [Push local changes](/docs/guides/git-push) Git action in {designer}, and select the **Publish** checkbox.

***

## Prerequisites

Before you begin, make sure you have the following:

* A [{maia} account](/docs/administration/registration).
* Valid API credentials for API access.
* An access token with the required privileges (refer to [Authentication](/docs/api-reference/maia-api-authentication) and [Get the access token](/docs/api-reference/maia-api-authentication#step-3-obtaining-the-access-token)).

***

### Step 1: Get the Project ID

Retrieve the list of projects using the [Project API](/api-reference/projects/list-all-projects).

Base URL: `GET /v1/projects`

Example response:

```json theme={null}
{
  "page": 0,
  "results": [
    {
      "description": "project-1",
      "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
      "name": "Test-project"
    }
  ],
  "size": 0,
  "total": 0
}
```

<Note>
  Make a note of the projects and their respective IDs, as you'll need these IDs when executing pipelines.
</Note>

### Step 2: Get the environment details

Once you have the project ID, use the [Environment API](/api-reference/environments/list-all-environments) to obtain details about the environment in which the project is running.

Base URL: `GET /v1/projects/{projectId}/environments`

Example Response:

```json theme={null}
{
  "page": 0,
  "results": [
    {
      "defaultAgentId": "3fa85f64-5717-4562-b3fc-2c963f66afaf",
      "defaultAgentName": "Dev Agent",
      "name": "Environment-1"
    }
  ],
  "size": 0,
  "total": 0
}
```

This includes the environment name (`name`), as well as the associated {m_runner}'s name (`defaultAgentName`) and {m_runner} ID (`defaultAgentID`).

### Step 3: Get the list of published pipelines

Retrieve the list of published pipelines using the [Pipeline API](/api-reference/pipelines/list-all-published-pipelines).

Base URL: `GET /v1/projects/{projectId}/published-pipelines`

Example response:

```json theme={null}
{
  "page": 0,
  "results": [
    {
      "name": "My pipeline",
      "publishedTime": "2023-11-24T10:39:02.182Z"
    }
  ],
  "size": 0,
  "total": 0
}
```

<Note>
  Review the available pipelines before execution.
</Note>

### Step 4: Execute published pipeline

To execute a [published pipeline](/api-reference/pipeline-execution/execute-published-pipeline), send a POST request with the project ID, environment name, and pipeline name.

Base URL: `POST /v1/projects/{projectId}/pipeline-executions`

Example request body:

```json theme={null}
{
  "pipelineName": "Pipeline 1",
  "environmentName": "Dev Environment"
}
```

Upon successful execution, you'll receive a pipeline execution ID needed for subsequent steps.

Example response:

```json theme={null}
{
  "pipelineExecutionId": "1398aa31-af57-4a6a-9752-27c2e8556c3f"
}
```

#### Execute a published pipeline using a specific artifact version

You can optionally specify a `versionName` in the request body to execute the pipeline in a specific published artifact. If you don't include `versionName`, the execution defaults to the latest artifact published to the environment.

Example request body with `versionName`:

```json theme={null}
{
  "pipelineName": "Dev Pipeline",
  "environmentName": "Dev Environment",
  "versionName": "1.1.1"
}
```

#### Execute a published pipeline while preventing concurrent executions

The API supports an optional `executionTag` parameter, which helps prevent concurrent executions of the same API call.

If the `executionTag` parameter is supplied, the pipeline will run with this tag. However, if another request is made with the same tag while the previous execution is still running, the request will fail with a `409` conflict response. This feature is particularly useful for external schedulers to prevent duplicate executions.

Example request body with `executionTag`:

```json theme={null}
{
  "pipelineName": "Pipeline 1",
  "environmentName": "Dev Environment",
  "executionTag": "nightly-run"
}
```

Example 409 conflict response if a duplicate execution is attempted:

```json theme={null}
{
  "error": "A pipeline execution with this tag is already running.",
  "status": 409
}
```

### Step 5: Check pipeline status

Optionally, check the pipeline status using the [Pipeline status](/api-reference/pipeline-execution/pipeline-execution-details) API with the project ID and pipeline execution ID.

Base URL: `GET /v1/projects/{projectId}/pipeline-executions/{pipelineExecutionId}`

Example response:

```json theme={null}
{
  "result": {
    "finishedAt": "2023-11-24T10:47:46.944Z",
    "message": "\"Rewrite Table\": Success",
    "startedAt": "2023-11-24T10:47:46.944Z",
    "status": "RUNNING"
  }
}
```

Possible values for `status` are `RUNNING`, `SUCCESS`, `FAILED`, `CANCELLING`, `CANCELLED`, `SKIPPED`, and `FORBIDDEN`. A pipeline execution has a `FORBIDDEN` status if the restricted {m_runner}'s allow list no longer permits this project/environment combination. For more information, read [Restrict a Maia runner](/docs/guides/restrict-a-runner).

You can also list pipeline executions and filter by status using the [List pipeline executions](/api-reference/pipeline-execution/pipeline-executions) endpoint, including `status=FORBIDDEN` to list only forbidden runs:

Base URL: `GET /v1/pipeline-executions?status=FORBIDDEN`

### Step 6: Terminate pipeline

To cancel a running pipeline, use the PATCH endpoint. Provide a request body with the force update and status details.

Base URL: `PATCH /v1/projects/{projectId}/pipeline-executions/{pipelineExecutionId}`

Example request body:

```json theme={null}

{
  "forceUpdate": true,
  "status": "My pipeline"
}
```

Upon successful termination, you'll receive a response along with the pipeline execution ID.

```json theme={null}
{
  "pipelineExecutionId": "1398aa31-af57-4a6a-9752-27c2e8556c3f"
}
```