# Executions

4 operations on the Logion v1 API.

- [List execution jobs.](#list-execution-jobs) — `GET /v1/executions/jobs`
- [Create an execution job.](#create-an-execution-job) — `POST /v1/executions/jobs`
- [Get one execution job with receipt summary and artifacts.](#get-one-execution-job-with-receipt-summary-and-artifacts) — `GET /v1/executions/jobs/{job_id}`
- [Cancel an execution job.](#cancel-an-execution-job) — `POST /v1/executions/jobs/{job_id}/cancel`

## List execution jobs.

```http
GET /v1/executions/jobs
```

Operation id: `list_execution_jobs`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `status` | query | string, optional | no |
| `job_type` | query | string, optional | no |
| `limit` | query | integer | no |
| `offset` | query | integer | no |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful Response | `ListExecutionJobsResponse` |
| `401` | Authentication required | `ErrorResponse` |
| `403` | Administrator access required | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `ListExecutionJobsResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `items` | ListExecutionJobsItemResponse[] | yes |  |
| `limit` | integer | yes |  |
| `offset` | integer | yes |  |
| `total` | integer | yes |  |

## Create an execution job.

```http
POST /v1/executions/jobs
```

Operation id: `create_execution_job`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Request body**

Body `CreateExecutionJobRequest`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `artifacts` | object[] | no |  |
| `contract_digest` | string, optional | no |  |
| `idempotency_key` | string, optional | no |  |
| `input_digests` | object, optional | no |  |
| `job_type` | string | yes | min length 1; max length 64 |
| `limits` | object, optional | no |  |
| `max_attempts` | integer, optional | no |  |
| `required_capabilities` | string[], optional | no |  |
| `resource_digest` | string, optional | no |  |
| `resource_id` | object, optional | no |  |
| `resource_version_id` | object, optional | no |  |
| `sandbox_profile` | SandboxProfile | yes |  |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Idempotent replay of an existing job | `CreateExecutionJobResponse` |
| `201` | Successful Response | `CreateExecutionJobResponse` |
| `401` | Authentication required | `ErrorResponse` |
| `403` | Administrator access required | `ErrorResponse` |
| `422` | Invalid execution job | `ErrorResponse` |

Returns `CreateExecutionJobResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `artifacts` | object[] | yes |  |
| `attempt_count` | integer | yes |  |
| `cancel_requested` | boolean | yes |  |
| `contract_digest` | string, optional | yes |  |
| `created_at` | object | yes |  |
| `id` | string | yes |  |
| `idempotency_key` | string, optional | yes |  |
| `input_digests` | object | yes |  |
| `job_type` | string | yes |  |
| `lease_expires_at` | object | yes |  |
| `lease_holder` | string, optional | yes |  |
| `limits` | object | yes |  |
| `max_attempts` | integer | yes |  |
| `required_capabilities` | object[], optional | yes |  |
| `resource_digest` | string, optional | yes |  |
| `resource_id` | string, optional | yes |  |
| `resource_version_id` | string, optional | yes |  |
| `sandbox_profile` | SandboxProfile | yes |  |
| `sandbox_profile_digest` | string, optional | yes |  |
| `status` | string | yes |  |
| `terminal_at` | object | yes |  |
| `terminal_transition_count` | integer | yes |  |
| `updated_at` | object | yes |  |

## Get one execution job with receipt summary and artifacts.

```http
GET /v1/executions/jobs/{job_id}
```

Operation id: `get_execution_job`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `job_id` | path | string(uuid) | yes |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful Response | `GetExecutionJobResponse` |
| `401` | Authentication required | `ErrorResponse` |
| `403` | Administrator access required | `ErrorResponse` |
| `404` | Execution job not found | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `GetExecutionJobResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `accepted_receipt` | object, optional | yes |  |
| `artifacts` | object[] | yes |  |
| `job` | object | yes |  |

## Cancel an execution job.

```http
POST /v1/executions/jobs/{job_id}/cancel
```

Operation id: `cancel_execution_job`

Takes an [`Authorization`](/docs/api/overview#authentication) header.

**Parameters**

| Name | In | Type | Required |
| --- | --- | --- | --- |
| `job_id` | path | string(uuid) | yes |

**Responses**

| Status | Meaning | Schema |
| --- | --- | --- |
| `200` | Successful Response | `CancelExecutionJobResponse` |
| `401` | Authentication required | `ErrorResponse` |
| `403` | Administrator access required | `ErrorResponse` |
| `404` | Execution job not found | `ErrorResponse` |
| `409` | Job is already terminal | `ErrorResponse` |
| `422` | Validation Error | `HTTPValidationError` |

Returns `CancelExecutionJobResponse`:

| Field | Type | Required | Notes |
| --- | --- | --- | --- |
| `cancel_requested` | boolean | yes |  |
| `id` | string | yes |  |
| `status` | string | yes |  |
| `terminal_at` | string(date-time), optional | yes |  |