> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corti.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Work with contexts

> Learn how to list, inspect, and delete contexts, and how to retrieve tasks within a context.

This guide shows you how to manage contexts using the v2 Agentic API. Contexts are first-class resources with their own endpoints for listing, inspection, and deletion.

## Prerequisites

* An existing agent with at least one sent message (see [Send a message](/agentic/guides/send-message))
* Understanding of [context and memory](/agentic/context-memory)

## List contexts

<Warning>The `GET /v2/agentic/contexts` listing endpoint is in private preview — it returns an empty list and ignores all filters. Use `GET /v2/agentic/contexts/{contextId}` to retrieve a specific context.</Warning>

```bash theme={null}
# Replace these with your values
ENVIRONMENT="<eu-or-us>"
TENANT="<your-tenant-name>"
TOKEN="<your-access-token>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

### Filtering

| Parameter | Description                                     |
| --------- | ----------------------------------------------- |
| `agentId` | Restrict to contexts owned by a specific agent  |
| `from`    | Inclusive lower bound on `createdAt` (RFC 3339) |
| `to`      | Exclusive upper bound on `createdAt` (RFC 3339) |

```bash theme={null}
AGENT_ID="<your-agent-id>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts?agentId=${AGENT_ID}&from=2026-05-19T00:00:00Z" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

The response is paginated with `contexts`, `nextPageToken`, and `totalSize` fields.

## Get a context

```bash theme={null}
CONTEXT_ID="<your-context-id>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

Use the `historyLength` query parameter to cap the number of history messages returned per task:

```bash theme={null}
curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}?historyLength=10" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

The response includes the context's metadata and its `tasks` array (oldest first). Each task carries its full message `history`.

```json theme={null}
{
  "id": "ctx.0192f4c8-...",
  "agentId": "agt.0192f4c8-...",
  "taskCount": 1,
  "createdAt": "2026-05-19T12:00:00Z",
  "updatedAt": "2026-05-19T12:00:01Z",
  "expiresAt": null,
  "tasks": [
    {
      "id": "task.0192f4c8-...",
      "contextId": "ctx.0192f4c8-...",
      "status": {"state": "TASK_STATE_COMPLETED", "timestamp": "2026-05-19T12:00:01Z"},
      "history": [
        {"role": "ROLE_USER", "messageId": "msg-...", "parts": [{"text": "Code this encounter."}]},
        {"role": "ROLE_AGENT", "messageId": "msg-...", "parts": [{"text": "J45.901"}]}
      ]
    }
  ]
}
```

## Delete a context

```bash theme={null}
curl -X DELETE "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

<Warning>Deleting a context is irreversible. All associated tasks, messages, and artifacts are permanently removed.</Warning>

## List tasks in a context

```bash theme={null}
curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}/tasks" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

## Get a specific task in a context

```bash theme={null}
TASK_ID="<your-task-id>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}/tasks/${TASK_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

## Get an artifact

Retrieve a specific artifact produced by a task:

```bash theme={null}
ARTIFACT_ID="<your-artifact-id>"

curl "https://api.${ENVIRONMENT}.corti.app/v2/agentic/contexts/${CONTEXT_ID}/tasks/${TASK_ID}/artifacts/${ARTIFACT_ID}" \
  -H "Authorization: Bearer ${TOKEN}" \
  -H "Tenant-Name: ${TENANT}"
```

## Next steps

* Learn how to [export traces](/agentic/guides/export-traces) for observability
* Read about [context and memory](/agentic/context-memory) concepts
* Learn how to [submit feedback](/agentic/guides/submit-feedback) on task results