Executions

This guide explains how to find execution resources, retrieve details, and cancel executions.

Why this matters

• Executions represent both long-running tasks (provisioning frontends for example) and immediate tasks (creating health checks for example).
• Provides an audit trail of changes to the Frontdoor account.

Assumptions

• The examples assume you have a valid Bearer token. If you need help obtaining a token, see [./auth](Auth Guide).
• Base URL for all API calls is https://gateway.production.netfoundry.io/frontdoor
• Expected headers for all API calls:

- Authorization: Bearer YOUR_ACCESS_TOKEN
- Accept: application/hal+json or application/json

Operations

Find execution by process ID

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/executions:find?processId=abc-123"

Response example

{
  "id": "exe-1",
  "processId": "abc-123",
  "status": "RUNNING",
  "startedAt": "2025-08-11T09:00:00Z"
}

Get an execution by ID

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/executions/exe-1

Response example

{
  "id": "exe-1",
  "processId": "abc-123",
  "status": "RUNNING",
  "startedAt": "2025-08-11T09:00:00Z"
}

Technical Notes

Paths

- GET /frontdoor/\{frontdoorId\}/executions[?page=0&size=20&sort=createdAt]
- GET /frontdoor/\{frontdoorId\}/executions/{id}

Common errors

400 Bad Request (client error)

{
  "error": "invalid_request",
  "message": "Value for <property> must be of <type>"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

401 Unauthorized (missing/expired token)

{
  "error": "unauthorized",
  "message": "Bearer token is missing or invalid"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

403 Forbidden (not_authorized)

{
  "error": "not_found",
  "message": "Frontdoor 3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c not found"
}

Possible reasons include:

• Invalid token: The token is not valid.
• The token does not grant access to the requested resource.
• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.