> 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.](/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" 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](/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**

```
POST /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>/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>"]'
```

### 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](/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](/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]: Beta features are feature-complete but still being validated. Available on request.