Execution Endpoints
Manage agent task execution state with checkpoints, pause and resume capabilities. Execution memory allows long-running agent tasks to survive interruptions and resume from the last known state.
Overview
The execution API provides durable task state management for agents. Tasks can save checkpoints at key milestones, be paused and resumed, and recover from failures by rolling back to the last checkpoint. This is essential for long-running operations like data processing, multi-step workflows, and complex research tasks.
| Method | Endpoint | Description |
|---|---|---|
POST | /v1/execution | Create a new execution task |
GET | /v1/execution/:taskId | Get execution task status |
PUT | /v1/execution/:taskId/checkpoint | Save a checkpoint |
POST | /v1/execution/:taskId/pause | Pause a running task |
POST | /v1/execution/:taskId/resume | Resume a paused task |
DELETE | /v1/execution/:taskId | Delete an execution task |
Create Execution
Get Execution
Save Checkpoint
Checkpoint frequency
Save checkpoints at meaningful milestones (e.g., after completing a stage or processing a batch of data). Frequent checkpoints reduce the amount of work lost on failure but add overhead. The checkpoint_interval_seconds config option can automate checkpoint timing.
Pause Execution
Resume Execution
Resuming from a specific checkpoint
If you omit the checkpoint_id, the task will resume from the most recent checkpoint. Specify an earlier checkpoint ID to roll back to a previous state -- useful when the latest state contains errors.
Delete Execution
Running tasks
If the task is currently running, it will be forcefully terminated before deletion. Consider pausing the task first if you need to preserve its current state before deciding to delete.
Execution Object
The following table describes all fields in an execution task object.
| Field | Type | Description |
|---|---|---|
id | string | Unique execution identifier (prefixed with exec_) |
name | string | Human-readable task name |
description | string | Description of the task purpose |
agent_id | string | ID of the agent executing the task |
task_type | string | Classification of the task type |
status | string | Current status: running, paused, completed, failed, terminated |
state | object | Current task state (arbitrary JSON reflecting progress) |
checkpoints | array | List of saved checkpoints with id, label, state, and timestamp |
config | object | Task configuration (max duration, checkpoint interval, retry settings) |
elapsed_seconds | integer | Total active execution time (excludes paused time) |
started_at | string | ISO 8601 timestamp when the task started |
completed_at | string | null | ISO 8601 timestamp when the task completed (null if still active) |
updated_at | string | ISO 8601 timestamp of the last state update |
