Letta · Capability
Letta API — Runs
Agent runs — inspect agent executions, step counts, usage, and run-scoped messages. 10 operations. Lead operation: List Runs. Self-contained Naftiko capability covering one Letta business surface.
Letta API — Runs is a Naftiko capability published by Letta, one of 36 capabilities the APIs.io network indexes for this provider. It bundles 10 operations across the GET, DELETE, and POST methods rooted at /v1/runs.
The capability includes 9 read-only operations and 1 state-changing operation. Lead operation: List Runs. Can be deployed as a REST endpoint, MCP tool, or Agent Skill via Naftiko.
Tagged areas include Letta, Stateful Agents, and Runs.
What You Can Do
GET
List_runs
— List Runs
/v1/runs/
GET
List_active_runs
— List Active Runs
/v1/runs/active
GET
Retrieve_run
— Retrieve Run
/v1/runs/{run-id}
DELETE
Delete_run
— Delete Run
/v1/runs/{run-id}
GET
List_messages_for_run
— List Messages for Run
/v1/runs/{run-id}/messages
GET
Retrieve_usage_for_run
— Retrieve Usage for Run
/v1/runs/{run-id}/usage
GET
Retrieve_metrics_for_run
— Retrieve Metrics for Run
/v1/runs/{run-id}/metrics
GET
List_steps_for_run
— List Steps for Run
/v1/runs/{run-id}/steps
GET
Retrieve_trace_for_run
— Retrieve Trace for Run
/v1/runs/{run-id}/trace
POST
Retrieve_stream_for_run
— Retrieve Stream for Run
/v1/runs/{run-id}/stream
MCP Tools
list-runs
List Runs
read-only
idempotent
list-active-runs
List Active Runs
read-only
idempotent
retrieve-run
Retrieve Run
read-only
idempotent
delete-run
Delete Run
idempotent
list-messages-run
List Messages for Run
read-only
idempotent
retrieve-usage-run
Retrieve Usage for Run
read-only
idempotent
retrieve-metrics-run
Retrieve Metrics for Run
read-only
idempotent
list-steps-run
List Steps for Run
read-only
idempotent
retrieve-trace-run
Retrieve Trace for Run
read-only
idempotent
retrieve-stream-run
Retrieve Stream for Run
read-only
Capability Spec
naftiko: "1.0.0-alpha2"
info:
label: "Letta API — Runs"
description: >-
Agent runs — inspect agent executions, step counts, usage, and run-scoped messages. 10 operations. Lead operation: List Runs. Self-contained Naftiko capability covering one Letta business surface.
tags:
- Letta
- Stateful Agents
- Runs
created: "2026-05-08"
modified: "2026-05-22"
binds:
- namespace: env
keys:
LETTA_API_KEY: LETTA_API_KEY
capability:
consumes:
- type: http
namespace: "letta-runs"
baseUri: "https://api.letta.com"
description: "Letta API — Runs business capability. Self-contained, no shared references."
authentication:
type: bearer
token: "{{env.LETTA_API_KEY}}"
resources:
- name: "runs"
path: "/v1/runs/"
operations:
- name: "list_runs"
method: GET
description: "List Runs"
inputParameters:
- name: "agent_id"
in: query
type: string
required: false
description: "The unique identifier of the agent associated with the run."
- name: "agent_ids"
in: query
type: string
required: false
description: "The unique identifiers of the agents associated with the run. Deprecated in favor of agent_id field."
- name: "statuses"
in: query
type: string
required: false
description: "Filter runs by status. Can specify multiple statuses."
- name: "background"
in: query
type: string
required: false
description: "If True, filters for runs that were created in background mode."
- name: "stop_reason"
in: query
type: string
required: false
description: "Filter runs by stop reason."
- name: "conversation_id"
in: query
type: string
required: false
description: "Filter runs by conversation ID."
- name: "before"
in: query
type: string
required: false
description: "Run ID cursor for pagination. Returns runs that come before this run ID in the specified sort order"
- name: "after"
in: query
type: string
required: false
description: "Run ID cursor for pagination. Returns runs that come after this run ID in the specified sort order"
- name: "limit"
in: query
type: string
required: false
description: "Maximum number of runs to return"
- name: "order"
in: query
type: string
required: false
description: "Sort order for runs by creation time. 'asc' for oldest first, 'desc' for newest first"
- name: "order_by"
in: query
type: string
required: false
description: "Field to sort by"
- name: "active"
in: query
type: boolean
required: false
description: "Filter for active runs."
- name: "ascending"
in: query
type: boolean
required: false
description: "Whether to sort agents oldest to newest (True) or newest to oldest (False, default). Deprecated in favor of order field."
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "runs-active"
path: "/v1/runs/active"
operations:
- name: "list_active_runs"
method: GET
description: "List Active Runs"
inputParameters:
- name: "agent_id"
in: query
type: string
required: false
description: "The unique identifier of the agent associated with the run."
- name: "background"
in: query
type: string
required: false
description: "If True, filters for runs that were created in background mode."
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "runs-by-id"
path: "/v1/runs/{run_id}"
operations:
- name: "retrieve_run"
method: GET
description: "Retrieve Run"
inputParameters:
- name: "run_id"
in: path
type: string
required: true
description: "run_id parameter"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "delete_run"
method: DELETE
description: "Delete Run"
inputParameters:
- name: "run_id"
in: path
type: string
required: true
description: "run_id parameter"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "runs-by-id-messages"
path: "/v1/runs/{run_id}/messages"
operations:
- name: "list_messages_for_run"
method: GET
description: "List Messages for Run"
inputParameters:
- name: "run_id"
in: path
type: string
required: true
description: "run_id parameter"
- name: "before"
in: query
type: string
required: false
description: "Message ID cursor for pagination. Returns messages that come before this message ID in the specified sort order"
- name: "after"
in: query
type: string
required: false
description: "Message ID cursor for pagination. Returns messages that come after this message ID in the specified sort order"
- name: "limit"
in: query
type: string
required: false
description: "Maximum number of messages to return"
- name: "order"
in: query
type: string
required: false
description: "Sort order for messages by creation time. 'asc' for oldest first, 'desc' for newest first"
- name: "order_by"
in: query
type: string
required: false
description: "Field to sort by"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "runs-by-id-usage"
path: "/v1/runs/{run_id}/usage"
operations:
- name: "retrieve_usage_for_run"
method: GET
description: "Retrieve Usage for Run"
inputParameters:
- name: "run_id"
in: path
type: string
required: true
description: "run_id parameter"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "runs-by-id-metrics"
path: "/v1/runs/{run_id}/metrics"
operations:
- name: "retrieve_metrics_for_run"
method: GET
description: "Retrieve Metrics for Run"
inputParameters:
- name: "run_id"
in: path
type: string
required: true
description: "run_id parameter"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "runs-by-id-steps"
path: "/v1/runs/{run_id}/steps"
operations:
- name: "list_steps_for_run"
method: GET
description: "List Steps for Run"
inputParameters:
- name: "run_id"
in: path
type: string
required: true
description: "run_id parameter"
- name: "before"
in: query
type: string
required: false
description: "Cursor for pagination"
- name: "after"
in: query
type: string
required: false
description: "Cursor for pagination"
- name: "limit"
in: query
type: string
required: false
description: "Maximum number of messages to return"
- name: "order"
in: query
type: string
required: false
description: "Sort order for steps by creation time. 'asc' for oldest first, 'desc' for newest first"
- name: "order_by"
in: query
type: string
required: false
description: "Field to sort by"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "runs-by-id-trace"
path: "/v1/runs/{run_id}/trace"
operations:
- name: "retrieve_trace_for_run"
method: GET
description: "Retrieve Trace for Run"
inputParameters:
- name: "run_id"
in: path
type: string
required: true
description: "run_id parameter"
- name: "limit"
in: query
type: integer
required: false
description: "Maximum number of spans to return"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
- name: "runs-by-id-stream"
path: "/v1/runs/{run_id}/stream"
operations:
- name: "retrieve_stream_for_run"
method: POST
description: "Retrieve Stream for Run"
inputParameters:
- name: "run_id"
in: path
type: string
required: true
description: "run_id parameter"
- name: "body"
in: body
type: object
required: true
description: "Request payload"
outputRawFormat: json
outputParameters:
- name: result
type: object
value: "$."
exposes:
- type: rest
namespace: "letta-runs-rest"
port: 8080
description: "REST adapter for Letta API — Runs. One Spectral-compliant resource per consumed operation."
resources:
- path: "/v1/runs/"
name: "runs"
description: "REST surface for runs."
operations:
- method: GET
name: "list_runs"
description: "List Runs"
call: "letta-runs.list_runs"
with:
"agent_id": "rest.agent_id"
"agent_ids": "rest.agent_ids"
"statuses": "rest.statuses"
"background": "rest.background"
"stop_reason": "rest.stop_reason"
"conversation_id": "rest.conversation_id"
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
"active": "rest.active"
"ascending": "rest.ascending"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/runs/active"
name: "runs-active"
description: "REST surface for runs-active."
operations:
- method: GET
name: "list_active_runs"
description: "List Active Runs"
call: "letta-runs.list_active_runs"
with:
"agent_id": "rest.agent_id"
"background": "rest.background"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/runs/{run-id}"
name: "runs-by-id"
description: "REST surface for runs-by-id."
operations:
- method: GET
name: "retrieve_run"
description: "Retrieve Run"
call: "letta-runs.retrieve_run"
with:
"run_id": "rest.run_id"
outputParameters:
- type: object
mapping: "$."
- method: DELETE
name: "delete_run"
description: "Delete Run"
call: "letta-runs.delete_run"
with:
"run_id": "rest.run_id"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/runs/{run-id}/messages"
name: "runs-by-id-messages"
description: "REST surface for runs-by-id-messages."
operations:
- method: GET
name: "list_messages_for_run"
description: "List Messages for Run"
call: "letta-runs.list_messages_for_run"
with:
"run_id": "rest.run_id"
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/runs/{run-id}/usage"
name: "runs-by-id-usage"
description: "REST surface for runs-by-id-usage."
operations:
- method: GET
name: "retrieve_usage_for_run"
description: "Retrieve Usage for Run"
call: "letta-runs.retrieve_usage_for_run"
with:
"run_id": "rest.run_id"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/runs/{run-id}/metrics"
name: "runs-by-id-metrics"
description: "REST surface for runs-by-id-metrics."
operations:
- method: GET
name: "retrieve_metrics_for_run"
description: "Retrieve Metrics for Run"
call: "letta-runs.retrieve_metrics_for_run"
with:
"run_id": "rest.run_id"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/runs/{run-id}/steps"
name: "runs-by-id-steps"
description: "REST surface for runs-by-id-steps."
operations:
- method: GET
name: "list_steps_for_run"
description: "List Steps for Run"
call: "letta-runs.list_steps_for_run"
with:
"run_id": "rest.run_id"
"before": "rest.before"
"after": "rest.after"
"limit": "rest.limit"
"order": "rest.order"
"order_by": "rest.order_by"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/runs/{run-id}/trace"
name: "runs-by-id-trace"
description: "REST surface for runs-by-id-trace."
operations:
- method: GET
name: "retrieve_trace_for_run"
description: "Retrieve Trace for Run"
call: "letta-runs.retrieve_trace_for_run"
with:
"run_id": "rest.run_id"
"limit": "rest.limit"
outputParameters:
- type: object
mapping: "$."
- path: "/v1/runs/{run-id}/stream"
name: "runs-by-id-stream"
description: "REST surface for runs-by-id-stream."
operations:
- method: POST
name: "retrieve_stream_for_run"
description: "Retrieve Stream for Run"
call: "letta-runs.retrieve_stream_for_run"
with:
"run_id": "rest.run_id"
"body": "rest.body"
outputParameters:
- type: object
mapping: "$."
- type: mcp
namespace: "letta-runs-mcp"
port: 9090
transport: http
description: "MCP adapter for Letta API — Runs. One verb-noun tool per consumed operation."
tools:
- name: "list-runs"
description: "List Runs"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-runs.list_runs"
with:
"agent_id": "tools.agent_id"
"agent_ids": "tools.agent_ids"
"statuses": "tools.statuses"
"background": "tools.background"
"stop_reason": "tools.stop_reason"
"conversation_id": "tools.conversation_id"
"before": "tools.before"
"after": "tools.after"
"limit": "tools.limit"
"order": "tools.order"
"order_by": "tools.order_by"
"active": "tools.active"
"ascending": "tools.ascending"
outputParameters:
- type: object
mapping: "$."
- name: "list-active-runs"
description: "List Active Runs"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-runs.list_active_runs"
with:
"agent_id": "tools.agent_id"
"background": "tools.background"
outputParameters:
- type: object
mapping: "$."
- name: "retrieve-run"
description: "Retrieve Run"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-runs.retrieve_run"
with:
"run_id": "tools.run_id"
outputParameters:
- type: object
mapping: "$."
- name: "delete-run"
description: "Delete Run"
hints:
readOnly: false
destructive: true
idempotent: true
call: "letta-runs.delete_run"
with:
"run_id": "tools.run_id"
outputParameters:
- type: object
mapping: "$."
- name: "list-messages-run"
description: "List Messages for Run"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-runs.list_messages_for_run"
with:
"run_id": "tools.run_id"
"before": "tools.before"
"after": "tools.after"
"limit": "tools.limit"
"order": "tools.order"
"order_by": "tools.order_by"
outputParameters:
- type: object
mapping: "$."
- name: "retrieve-usage-run"
description: "Retrieve Usage for Run"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-runs.retrieve_usage_for_run"
with:
"run_id": "tools.run_id"
outputParameters:
- type: object
mapping: "$."
- name: "retrieve-metrics-run"
description: "Retrieve Metrics for Run"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-runs.retrieve_metrics_for_run"
with:
"run_id": "tools.run_id"
outputParameters:
- type: object
mapping: "$."
- name: "list-steps-run"
description: "List Steps for Run"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-runs.list_steps_for_run"
with:
"run_id": "tools.run_id"
"before": "tools.before"
"after": "tools.after"
"limit": "tools.limit"
"order": "tools.order"
"order_by": "tools.order_by"
outputParameters:
- type: object
mapping: "$."
- name: "retrieve-trace-run"
description: "Retrieve Trace for Run"
hints:
readOnly: true
destructive: false
idempotent: true
call: "letta-runs.retrieve_trace_for_run"
with:
"run_id": "tools.run_id"
"limit": "tools.limit"
outputParameters:
- type: object
mapping: "$."
- name: "retrieve-stream-run"
description: "Retrieve Stream for Run"
hints:
readOnly: true
destructive: false
idempotent: false
call: "letta-runs.retrieve_stream_for_run"
with:
"run_id": "tools.run_id"
"body": "tools.body"
outputParameters:
- type: object
mapping: "$."