For the complete documentation index, see llms.txt. This page is also available as Markdown.
BETA

Delegate Executions API

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

This feature is in Beta and requires enablement. View all early access features.

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

Before you begin

  • 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

Endpoint

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

Request parameters

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

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.

Example request

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

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

  • 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

The API returns NOT_FOUND for an execution I know ran recently

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.

Next steps

  • Overview: Learn about the Delegate 3.x execution model and how stage executions map to delegate tasks.

  • Feature Parity: Review the current support matrix for Delegate 3.x.

Last updated

Was this helpful?