Task-runs

For instructions on how to authenticate to use this endpoint, see API overview.

Endpoints

GET
POST
GET
PATCH
POST
POST
POST
PATCH

List all tasks runs

Required API key scopes

task:read

Path parameters

  • project_id
    string
  • task_id
    string

Query parameters

  • limit
    integer
  • offset
    integer

Response


Example request

GET /api/projects/:project_id/tasks/:task_id/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/

Example response

Status 200 List of task runs
RESPONSE
{
  "count": 123,
  "next": "http://api.example.org/accounts/?offset=400&limit=100",
  "previous": "http://api.example.org/accounts/?offset=200&limit=100",
  "results": [
    {
      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
      "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
      "stage": "string",
      "branch": "string",
      "status": "not_started",
      "environment": "local",
      "log_url": "string",
      "error_message": "string",
      "output": null,
      "state": null,
      "artifacts": [
        {
          "name": "string",
          "type": "string",
          "size": 0,
          "content_type": "string",
          "storage_path": "string",
          "uploaded_at": "string"
        }
      ],
      "created_at": "2019-08-24T14:15:22Z",
      "updated_at": "2019-08-24T14:15:22Z",
      "completed_at": "2019-08-24T14:15:22Z"
    }
  ]
}

Create tasks runs

Create a new run for a specific task.

Required API key scopes

task:write

Path parameters

  • project_id
    string
  • task_id
    string

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/

Example response

Status 201 Created task run
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "not_started",
  "environment": "local",
  "log_url": "string",
  "error_message": "string",
  "output": null,
  "state": null,
  "artifacts": [
    {
      "name": "string",
      "type": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}

Retrieve tasks runs

API for managing task runs. Each run represents an execution of a task.

Required API key scopes

task:read

Path parameters

  • id
    string
  • project_id
    string
  • task_id
    string

Response


Example request

GET /api/projects/:project_id/tasks/:task_id/runs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/

Example response

Status 200
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "not_started",
  "environment": "local",
  "log_url": "string",
  "error_message": "string",
  "output": null,
  "state": null,
  "artifacts": [
    {
      "name": "string",
      "type": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}

Update tasks runs

API for managing task runs. Each run represents an execution of a task.

Required API key scopes

task:write

Path parameters

  • id
    string
  • project_id
    string
  • task_id
    string

Request parameters

  • status
  • branch
    string
  • stage
    string
  • output
  • state
  • error_message
    string

Response


Example request

PATCH /api/projects/:project_id/tasks/:task_id/runs/:id
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/\
	-d status=undefined

Example response

Status 200 Updated task run
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "not_started",
  "environment": "local",
  "log_url": "string",
  "error_message": "string",
  "output": null,
  "state": null,
  "artifacts": [
    {
      "name": "string",
      "type": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}
Status 400 Invalid update data
RESPONSE
{
  "error": {
    "property1": null,
    "property2": null
  }
}
Status 404 Task run not found

Create tasks runs append log

Append one or more log entries to the task run log array

Required API key scopes

task:write

Path parameters

  • id
    string
  • project_id
    string
  • task_id
    string

Request parameters

  • entries
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/append_log
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/append_log/\
	-d entries="array"

Example response

Status 200 Run with updated log
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "not_started",
  "environment": "local",
  "log_url": "string",
  "error_message": "string",
  "output": null,
  "state": null,
  "artifacts": [
    {
      "name": "string",
      "type": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}
Status 400 Invalid log entries
RESPONSE
{
  "error": {
    "property1": null,
    "property2": null
  }
}
Status 404 Run not found

Create tasks runs artifacts

Persist task artifacts to S3 and attach them to the run manifest.

Required API key scopes

task:write

Path parameters

  • id
    string
  • project_id
    string
  • task_id
    string

Request parameters

  • artifacts
    Click to open
    array

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/\
	-d artifacts="array"

Example response

Status 200 Run with updated artifact manifest
RESPONSE
{
  "artifacts": [
    {
      "name": "string",
      "type": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ]
}
Status 400 Invalid artifact payload
RESPONSE
{
  "error": {
    "property1": null,
    "property2": null
  }
}
Status 404 Run not found

Create tasks runs artifacts presign

Returns a temporary, signed URL that can be used to download a specific artifact.

Required API key scopes

task:read

Path parameters

  • id
    string
  • project_id
    string
  • task_id
    string

Request parameters

  • storage_path
    string

Response


Example request

POST /api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/presign
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl 
    -H 'Content-Type: application/json'\
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/artifacts/presign/\
	-d storage_path="string"

Example response

Status 200 Presigned URL for the requested artifact
RESPONSE
{
  "url": "http://example.com",
  "expires_in": 0
}
Status 400 Invalid request
RESPONSE
{
  "error": {
    "property1": null,
    "property2": null
  }
}
Status 404 Artifact not found

Update tasks runs set output

Update the output field for a task run (e.g., PR URL, commit SHA, etc.)

Required API key scopes

task:write

Path parameters

  • id
    string
  • project_id
    string
  • task_id
    string

Response


Example request

PATCH /api/projects/:project_id/tasks/:task_id/runs/:id/set_output
export POSTHOG_PERSONAL_API_KEY=[your personal api key]
curl -X PATCH \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    <ph_app_host>/api/projects/:project_id/tasks/:task_id/runs/:id/set_output/

Example response

Status 200 Run with updated output
RESPONSE
{
  "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
  "task": "4879b8a6-fb3e-4a0d-aef8-b0ea469ac85c",
  "stage": "string",
  "branch": "string",
  "status": "not_started",
  "environment": "local",
  "log_url": "string",
  "error_message": "string",
  "output": null,
  "state": null,
  "artifacts": [
    {
      "name": "string",
      "type": "string",
      "size": 0,
      "content_type": "string",
      "storage_path": "string",
      "uploaded_at": "string"
    }
  ],
  "created_at": "2019-08-24T14:15:22Z",
  "updated_at": "2019-08-24T14:15:22Z",
  "completed_at": "2019-08-24T14:15:22Z"
}
Status 404 Run not found

Community questions

Questions about this page? or post a community question.