> For the complete documentation index, see [llms.txt](https://developer.harness.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.harness.io/harness-platform/use-harness-platform/delegates/delegate-3x-closed-beta/delegate-executions-api.md).

# Delegate Executions API

Query delegate assignment status for Delegate 3.x stage executions.

{% hint style="info" %}
This feature is in Beta[^1] and requires enablement. [View all early access features.](https://developer.harness.io/release-notes/features.md)

{% @harness-feature-flag-access/request-feature-flag-access module="platform" pagePath="platform/use-harness-platform/delegates/delegate-3x-closed-beta/delegate-executions-api" pageTitle="Delegate%20Executions%20API" featureFlags="%5B%7B%22name%22%3A%22Delegate%20executions%20API%22%2C%22key%22%3A%22PL\_ENABLE\_DELEGATE\_EXECUTIONS\_API%22%2C%22status%22%3A%22BETA%22%2C%22description%22%3A%22Enables%20the%20delegate-executions%20API%2C%20which%20returns%20the%20delegate%20assignment%20status%20for%20Delegate%203.x%20(unified%2C%20runner-based)%20stage%20executions.%22%7D%5D" %}
{% endhint %}

{% hint style="warning" %}
**CLOSED BETA**

Delegate 3.x is currently in closed beta and available only to select users. The product team determines access based on current supported use cases. Go to [Feature Parity](https://developer.harness.io/harness-platform/use-harness-platform/delegates/delegate-3x-closed-beta/feature-parity.md) for the latest details.
{% endhint %}

The delegate executions API reports whether a delegate was assigned to a Delegate 3.x stage execution. Use it to check the delegate assignment status for one or more stage executions.

### What you will learn from this topic <a href="#what-you-will-learn-from-this-topic" id="what-you-will-learn-from-this-topic"></a>

* How to [use the delegate executions API endpoint](#use-the-api-endpoint).
* How to [read the response](#response-format), including each possible status value.
* [Limitations](#limitations) on which executions the API can return, including the retention window.

### Before you begin <a href="#before-you-begin" id="before-you-begin"></a>

* Contact Harness Support to enable `PL_ENABLE_DELEGATE_EXECUTIONS_API` on your account. The flag is not self-serve.
* The API only works for stages that ran on Delegate 3.x. Stages that ran on the classic (1.x) delegate are not supported.

### Use the API endpoint <a href="#use-the-api-endpoint" id="use-the-api-endpoint"></a>

**Endpoint**

```http
POST /gateway/ng/api/delegate-executions?accountIdentifier={accountIdentifier}
```

**Request parameters**

The request body is a JSON array of up to 100 execution ID strings.

```json
["<STAGE_EXECUTION_ID_1>", "<STAGE_EXECUTION_ID_2>"]
```

| Parameter           | Required | Description                                                                   |
| ------------------- | -------- | ----------------------------------------------------------------------------- |
| `accountIdentifier` | Yes      | Your Harness account identifier, passed as a query parameter.                 |
| Request body        | Yes      | A JSON array of up to 100 CI stage execution IDs, not pipeline execution IDs. |

{% hint style="warning" %}
Pass the **stage execution ID** of the CI stage, not the pipeline execution ID. Passing a pipeline execution ID returns `NOT_FOUND` for that entry.
{% endhint %}

**Example request**

```bash
curl --location 'https://<HOST>/gateway/ng/api/delegate-executions?accountIdentifier=<ACCOUNT_ID>' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <PAT_OR_SAT>' \
--data '["<STAGE_EXECUTION_ID_1>", "<STAGE_EXECUTION_ID_2>"]'
```

**Find a stage execution ID**

The delegate executions API requires a CI stage execution ID, not a pipeline execution ID.

To find it:

* Call `GET /pipelines/execution/v2/{planExecutionId}` for the pipeline execution.
* In the response, check `data.pipelineExecutionSummary.layoutNodeMap` for the stage by name, and take its `nodeExecutionId`. This value is the stage execution ID.
* If you already know the stage node ID, go directly to `data.pipelineExecutionSummary.layoutNodeMap['<STAGE_NODE_ID>'].nodeExecutionId`.

### Response format <a href="#response-format" id="response-format"></a>

The endpoint returns a map of each execution ID to a status.

| Status      | Meaning                                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------------------ |
| `ASSIGNED`  | A delegate was assigned. Delegate details are filled in: ID, name, hostname, delegate group identifier, and owner. |
| `QUEUED`    | The record is active, but no delegate has picked it up yet.                                                        |
| `TIMED_OUT` | The record was closed without a delegate ever being assigned.                                                      |
| `NOT_FOUND` | No record exists for that ID.                                                                                      |

If `PL_ENABLE_DELEGATE_EXECUTIONS_API` is not enabled for your account, the endpoint returns an `InvalidRequestException` indicating the API is not enabled.

### Limitations <a href="#limitations" id="limitations"></a>

* **Delegate 3.x only**: The API only works for Delegate 3.x stage executions. Classic (1.x) delegate executions are not supported.
* **Stage execution ID, not pipeline execution ID**: Pass the CI stage execution ID. A pipeline execution ID returns `NOT_FOUND`.
* **One day retention**: Execution records are retained for approximately 24 hours after a stage finishes cleanup. Querying an execution older than that returns `NOT_FOUND`.

### Troubleshooting <a href="#troubleshooting" id="troubleshooting"></a>

<details>

<summary>The API returns NOT_FOUND for an execution I know ran recently</summary>

Check the following:

* You passed the CI stage execution ID, not the pipeline execution ID.
* The stage ran on Delegate 3.x, not the classic delegate.
* The stage finished within the last 24 hours. Records older than that are removed.
* `PL_ENABLE_DELEGATE_EXECUTIONS_API` is enabled for your account.

If the issue persists, run a new pipeline on Delegate 3.x and query the API with its stage execution ID to confirm the flag and endpoint are working for your account.

</details>

### Next steps <a href="#next-steps" id="next-steps"></a>

* [Overview](https://developer.harness.io/harness-platform/use-harness-platform/delegates/delegate-3x-closed-beta/delegate-overview.md): Learn about the Delegate 3.x execution model and how stage executions map to delegate tasks.
* [Feature Parity](https://developer.harness.io/harness-platform/use-harness-platform/delegates/delegate-3x-closed-beta/feature-parity.md): Review the current support matrix for Delegate 3.x.

{% @harness-feedback/feedback %}

[^1]: Off by default. If you want to try it and share feedback, request access and Harness will turn it on for your account. Beta features can change and may not be ready for production use.
