Delegate Executions API
Query delegate assignment status for Delegate 3.x stage executions.
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
How to read the response, including each possible status value.
Limitations on which executions the API can return, including the retention window.
Before you begin
Contact Harness Support to enable
PL_ENABLE_DELEGATE_EXECUTIONS_APIon 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.
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.layoutNodeMapfor the stage by name, and take itsnodeExecutionId. 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.
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
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?