---
title: "Executions"
description: "Create, inspect and cancel Context4 tool executions: API requests, responses, attempts and errors."
group: "Technical documentation"
order: 31
---

## Deployment addresses

- Documentation: https://ctx4.me/docs.md
- Agent index: https://ctx4.me/docs/agent-index.json
- Console and connections: https://console.ctx4.me/integrations
- MCP: https://ctx4.me/mcp
- HTTP API: https://ctx4.me/v1
- Composio base URL: https://ctx4.me/compat/context4/v1
- OpenAPI: https://ctx4.me/docs/openapi.json
- HTTP/MCP inventory: https://ctx4.me/docs/api-index.json
- Composio routes: https://ctx4.me/docs/compat-routes.json
- Connectors: https://ctx4.me/docs/connectors.json


# Executions

Generated from the public Context4 OpenAPI. Authenticate with `Authorization: Bearer` and an API key. General rules: [API](https://ctx4.me/docs/api.md). Full contract: [OpenAPI JSON](https://ctx4.me/docs/openapi.json). In the JSON below, `$ref` points to a named schema in the Schemas section.

## createExecution

`POST /v1/executions`

Deployment URL: `https://ctx4.me/v1/executions`. Replace parameters in braces with actual IDs from the API.

Create an execution (asynchronous, idempotent)

Capability: `executions:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `Idempotency-Key` | header | yes | {"type":"string"} Client-chosen key (8-128 chars of [A-Za-z0-9._:-]); replays with the same payload return the original outcome |

### Request body

Required. [CreateExecutionRequest](https://ctx4.me/docs/api-schemas-1.md#createexecutionrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CreateExecutionRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 202 | Execution accepted (queued) or persisted as rejected with a denial code; poll the Location header | `application/json` [Execution](https://ctx4.me/docs/api-schemas-1.md#execution) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing, forbidden, session_expired, session_revoked, session_call_budget_exhausted) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (idempotency_conflict) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  },
  "Location": {
    "description": "Resource location (/v1/executions/{executionId})",
    "schema": {
      "type": "string"
    }
  }
}
```

## listExecutions

`GET /v1/executions`

Deployment URL: `https://ctx4.me/v1/executions`. Replace parameters in braces with actual IDs from the API.

List executions

Capability: `executions:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `status` | query | no | {"type":"string","enum":["requested","queued","running","retrying","succeeded","failed","rejected","cancelled"]}  |
| `connector_id` | query | no | {"type":"string","pattern":"^[a-z0-9][a-z0-9-]{1,78}$","example":"bitrix24"}  |
| `user_id` | query | no | {"$ref":"#/components/schemas/ExecutionEndUserRef"}  |
| `from` | query | no | {"type":"string","format":"date-time","example":"2026-07-16T12:00:00.000Z"}  |
| `to` | query | no | {"type":"string","format":"date-time","example":"2026-07-16T12:00:00.000Z"}  |
| `cursor` | query | no | {"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$","description":"Opaque pagination cursor from a previous response"} Opaque pagination cursor from a previous response |
| `limit` | query | no | {"type":"integer","minimum":1,"maximum":100,"description":"Page size (1-100, default 20)"} Page size (1-100, default 20) |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Executions ordered by creation time (descending) | `application/json` [ExecutionListResponse](https://ctx4.me/docs/api-schemas-1.md#executionlistresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## getExecution

`GET /v1/executions/{executionId}`

Deployment URL: `https://ctx4.me/v1/executions/{executionId}`. Replace parameters in braces with actual IDs from the API.

Get one execution with its result

Capability: `executions:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `executionId` | path | yes | {"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"}  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Execution view; terminal successes include the result | `application/json` [ExecutionWithResult](https://ctx4.me/docs/api-schemas-1.md#executionwithresult) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## listExecutionAttempts

`GET /v1/executions/{executionId}/attempts`

Deployment URL: `https://ctx4.me/v1/executions/{executionId}/attempts`. Replace parameters in braces with actual IDs from the API.

List execution attempts

Capability: `executions:read`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `executionId` | path | yes | {"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"}  |

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | Append-only attempt records | `application/json` [AttemptListResponse](https://ctx4.me/docs/api-schemas-1.md#attemptlistresponse) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```

## cancelExecution

`POST /v1/executions/{executionId}/cancel`

Deployment URL: `https://ctx4.me/v1/executions/{executionId}/cancel`. Replace parameters in braces with actual IDs from the API.

Cancel a queued execution

Capability: `executions:write`.

### Parameters

| Name | Location | Required | Type and constraints |
| --- | --- | --- | --- |
| `executionId` | path | yes | {"type":"string","format":"uuid","example":"9b2f6f2e-4b0a-4bd2-8b7e-3f8a1c2d4e5f"}  |

### Request body

Required. [CancelExecutionRequest](https://ctx4.me/docs/api-schemas-1.md#cancelexecutionrequest)

```json
{
  "required": true,
  "content": {
    "application/json": {
      "schema": {
        "$ref": "#/components/schemas/CancelExecutionRequest"
      }
    }
  }
}
```

### Responses and errors

| HTTP | Meaning | Format and schema |
| --- | --- | --- |
| 200 | The cancelled execution | `application/json` [Execution](https://ctx4.me/docs/api-schemas-1.md#execution) |
| 400 | Problem (validation_failed) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 401 | Problem (authentication_required, invalid_api_key, api_key_expired, api_key_revoked) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 403 | Problem (capability_missing) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 404 | Problem (not_found) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 409 | Problem (conflict, execution_not_cancellable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 429 | Problem (rate_limited) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 500 | Problem (internal) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |
| 503 | Problem (service_unavailable) | `application/problem+json` [Problem](https://ctx4.me/docs/api-schemas-1.md#problem) |

Successful response headers:
```json
{
  "X-Request-Id": {
    "description": "Correlation id echoed on every response",
    "schema": {
      "type": "string"
    }
  },
  "RateLimit-Limit": {
    "description": "Per-key request limit for the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Remaining": {
    "description": "Requests remaining in the current window",
    "schema": {
      "type": "integer"
    }
  },
  "RateLimit-Reset": {
    "description": "Seconds until the current window resets",
    "schema": {
      "type": "integer"
    }
  }
}
```