# Executions

> Understand the agent execution lifecycle, status types, input/output capture, token usage, cost tracking, and async execution.

Source: https://0.0.0.0:8080/docs/executions

An execution represents a single invocation of an agent. It captures the full lifecycle from input to output, including status, duration, token usage, cost, and metadata.

## Execution Lifecycle

When an agent is executed, the following steps occur:

1. **Pending** -- The execution is created and queued
2. **Running** -- The execution pipeline is actively processing (prompt rendering, LLM calls, tool invocations, guardrail checks)
3. **Terminal state** -- The execution reaches one of: completed, failed, cancelled, awaiting_approval, or rejected

```
pending -> running -> completed
                   -> failed
                   -> cancelled
                   -> awaiting_approval -> approved -> completed
                                        -> rejected
```

## Status Types

| Status              | Description                                                     |
| ------------------- | --------------------------------------------------------------- |
| `pending`           | Execution created, waiting to be processed                      |
| `running`           | Actively executing (LLM calls, tools, etc.)                     |
| `completed`         | Successfully finished with output                               |
| `failed`            | Encountered an error during execution                           |
| `cancelled`         | Manually cancelled before completion                            |
| `awaiting_approval` | Paused at a checkpoint, waiting for human approval              |
| `rejected`          | Human reviewer rejected the execution at an approval checkpoint |

## Input and Output

### Input

The input is a JSON object provided when executing an agent. It must conform to the agent version's input schema (if defined).

```json
{
  "message": "What is the status of order #12345?",
  "customer_id": "cust_789",
  "language": "en"
}
```

### Output

The output is the result produced by the agent after successful execution. The structure depends on the agent type and configuration.

```json
{
  "response": "Your order #12345 is currently in transit and expected to arrive by Friday.",
  "confidence": 0.95,
  "sources": ["order_database"]
}
```

## Token Usage and Cost

Every execution tracks token consumption and cost:

| Field         | Description                                                       |
| ------------- | ----------------------------------------------------------------- |
| `token_usage` | JSON object with prompt and completion token counts               |
| `cost`        | Total cost in USD (calculated from token usage and model pricing) |
| `duration_ms` | Total execution time in milliseconds                              |

Token usage example:

```json
{
  "prompt_tokens": 450,
  "completion_tokens": 120,
  "total_tokens": 570
}
```

## Metadata

Executions can carry arbitrary metadata for tracking and filtering:

```python
result = client.agents.execute(
    agent_id="your-agent-id",
    input={"message": "Hello"},
    metadata={
        "user_id": "user-456",
        "channel": "web",
        "environment": "production",
        "experiment_id": "exp-001"
    }
)
```

## Sync vs Async Execution

### Synchronous Execution

The default execution mode. The API call blocks until the execution completes and returns the result.

```python
result = client.agents.execute(
    agent_id="your-agent-id",
    input={"message": "Hello"}
)
# Result is immediately available
print(result["data"]["output"])
```

### Asynchronous Execution

For long-running executions, use async mode. The API returns immediately with the execution ID, and you poll for completion.

```python
# Start async execution
execution = client.agents.execute(
    agent_id="your-agent-id",
    input={"message": "Analyze this large dataset..."},
    async_mode=True
)

execution_id = execution["data"]["id"]

# Poll for completion
import time
while True:
    status = client.executions.get(execution_id=execution_id)
    if status["data"]["status"] in ["completed", "failed", "rejected"]:
        break
    time.sleep(1)

print(status["data"]["output"])
```

## Streaming Execution Events

Instead of polling, subscribe to the execution's Server-Sent Events
stream to receive `thinking`, `tool_start`, `tool_end`, `content`, and
`done` frames as they happen.

```
GET /api/v1/executions/{execution_id}/stream
Accept: text/event-stream
```

The event schema is identical to the chat streaming endpoint — see
[Sessions and Chat](/docs/sessions-and-chat#streaming-responses-sse)
for the full table. Useful when the execution was started outside a
chat session (e.g. a one-shot `agents.execute` or a webhook trigger)
and you still want live updates.

```typescript
// JavaScript / TypeScript
for await (const event of client.executions.stream(executionId)) {
  if (event.type === 'content') process.stdout.write(event.content)
  if (event.type === 'done') break
}
```

```python
# Python — sync iterator (AsyncExecutionsResource.stream for async)
from promptrails import ContentEvent, DoneEvent

for event in client.executions.stream(execution_id):
    if isinstance(event, ContentEvent):
        print(event.content, end="", flush=True)
    elif isinstance(event, DoneEvent):
        break
```

```go
// Go
stream, _ := client.Executions.Stream(ctx, executionID)
defer stream.Close()
for stream.Next() {
    if e, ok := stream.Event().(*promptrails.ContentEvent); ok {
        fmt.Print(e.Content)
    }
}
```

Already-completed executions emit a single `done` (or `error`) frame
and close, so the same code works whether you subscribe mid-run or
after the fact.

## Listing and Filtering Executions

```python
# List all executions
executions = client.executions.list(page=1, limit=20)

# Filter by agent
executions = client.executions.list(
    agent_id="your-agent-id",
    page=1,
    limit=20
)

# Filter by status
executions = client.executions.list(
    status="completed",
    page=1,
    limit=20
)
```

**JavaScript SDK**

```typescript
const executions = await client.executions.list({
  agentId: 'your-agent-id',
  status: 'completed',
  page: 1,
  limit: 20,
})
```

## Execution Response Fields

| Field              | Type      | Description                                         |
| ------------------ | --------- | --------------------------------------------------- |
| `id`               | KSUID     | Unique execution identifier                         |
| `agent_id`         | KSUID     | The agent that was executed                         |
| `agent_version_id` | KSUID     | The specific agent version used                     |
| `workspace_id`     | KSUID     | Workspace scope                                     |
| `user_id`          | KSUID     | User who initiated the execution (if authenticated) |
| `session_id`       | string    | Chat session ID (if applicable)                     |
| `status`           | string    | Current execution status                            |
| `input`            | JSON      | Input provided to the agent                         |
| `output`           | JSON      | Result produced by the agent                        |
| `error`            | string    | Error message (if failed)                           |
| `metadata`         | JSON      | Custom metadata                                     |
| `token_usage`      | JSON      | Token consumption breakdown                         |
| `cost`             | float     | Total cost in USD                                   |
| `duration_ms`      | integer   | Total duration in milliseconds                      |
| `trace_id`         | string    | Link to the execution trace                         |
| `started_at`       | timestamp | When execution started                              |
| `completed_at`     | timestamp | When execution finished                             |
| `created_at`       | timestamp | When the execution record was created               |

## Related Topics

- [Agents](/docs/agents) -- Executing agents
- [Tracing](/docs/tracing) -- Detailed execution traces
- [Cost Tracking](/docs/cost-tracking) -- Cost analysis
- [Approvals](/docs/approvals) -- Human-in-the-loop execution flow
- [Scoring and Evaluation](/docs/scoring-and-evaluation) -- Scoring executions