Installation
pip install telnyx
Setup
import os
from telnyx import Telnyx
client = Telnyx( api_key=os.environ.get("TELNYX_API_KEY"), # This is the default and can be omitted )
All examples below assume `client` is already initialized as shown above.
## Error Handling
All API calls can fail with network errors, rate limits (429), validation errors (422),
or authentication errors (401). Always handle errors in production code:
```python
import telnyx
try:
result = client.messages.send(to="+13125550001", from_="+13125550002", text="Hello")
except telnyx.APIConnectionError:
print("Network error — check connectivity and retry")
except telnyx.RateLimitError:
# 429: rate limited — wait and retry with exponential backoff
import time
time.sleep(1) # Check Retry-After header for actual delay
except telnyx.APIStatusError as e:
print(f"API error {e.status_code}: {e.message}")
if e.status_code == 422:
print("Validation error — check required fields and formats")
Common error codes: 401 invalid API key, 403 insufficient permissions,
404 resource not found, 422 validation error (check field formats),
429 rate limited (retry with exponential backoff).
Important Notes
- Pagination: List methods return an auto-paginating iterator. Use
for item in page_result:to iterate through all pages automatically.
List missions
List all missions for the organization
GET /ai/missions
page = client.ai.missions.list()
page = page.data[0]
print(page.mission_id)
Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)
Create mission
Create a new mission definition
POST /ai/missions — Required: name
Optional: description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), model (string)
mission = client.ai.missions.create(
name="my-resource",
)
print(mission.data)
Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)
List recent events
List recent events across all missions
GET /ai/missions/events
page = client.ai.missions.list_events()
page = page.data[0]
print(page.event_id)
Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)
List recent runs
List recent runs across all missions
GET /ai/missions/runs
page = client.ai.missions.runs.list_runs()
page = page.data[0]
print(page.mission_id)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Get mission
Get a mission by ID (includes tools, knowledge_bases, mcp_servers)
GET /ai/missions/{mission_id}
mission = client.ai.missions.retrieve(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(mission.data)
Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)
Update mission
Update a mission definition
PUT /ai/missions/{mission_id}
Optional: description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), model (string), name (string)
response = client.ai.missions.update_mission(
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: created_at (date-time), description (string), execution_mode (enum: external, managed), instructions (string), metadata (object), mission_id (uuid), model (string), name (string), updated_at (date-time)
Delete mission
Delete a mission
DELETE /ai/missions/{mission_id}
client.ai.missions.delete_mission(
"182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
Clone mission
Clone an existing mission
POST /ai/missions/{mission_id}/clone
response = client.ai.missions.clone_mission(
"mission_id",
)
print(response)
List knowledge bases
List all knowledge bases for a mission
GET /ai/missions/{mission_id}/knowledge-bases
response = client.ai.missions.knowledge_bases.list_knowledge_bases(
"mission_id",
)
print(response)
Create knowledge base
Create a new knowledge base for a mission
POST /ai/missions/{mission_id}/knowledge-bases
response = client.ai.missions.knowledge_bases.create_knowledge_base(
"mission_id",
)
print(response)
Get knowledge base
Get a specific knowledge base by ID
GET /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}
response = client.ai.missions.knowledge_bases.get_knowledge_base(
knowledge_base_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Update knowledge base
Update a knowledge base definition
PUT /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}
response = client.ai.missions.knowledge_bases.update_knowledge_base(
knowledge_base_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Delete knowledge base
Delete a knowledge base from a mission
DELETE /ai/missions/{mission_id}/knowledge-bases/{knowledge_base_id}
client.ai.missions.knowledge_bases.delete_knowledge_base(
knowledge_base_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
List MCP servers
List all MCP servers for a mission
GET /ai/missions/{mission_id}/mcp-servers
response = client.ai.missions.mcp_servers.list_mcp_servers(
"mission_id",
)
print(response)
Create MCP server
Create a new MCP server for a mission
POST /ai/missions/{mission_id}/mcp-servers
response = client.ai.missions.mcp_servers.create_mcp_server(
"mission_id",
)
print(response)
Get MCP server
Get a specific MCP server by ID
GET /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}
response = client.ai.missions.mcp_servers.get_mcp_server(
mcp_server_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Update MCP server
Update an MCP server definition
PUT /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}
response = client.ai.missions.mcp_servers.update_mcp_server(
mcp_server_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Delete MCP server
Delete an MCP server from a mission
DELETE /ai/missions/{mission_id}/mcp-servers/{mcp_server_id}
client.ai.missions.mcp_servers.delete_mcp_server(
mcp_server_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
List runs for mission
List all runs for a specific mission
GET /ai/missions/{mission_id}/runs
page = client.ai.missions.runs.list(
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
page = page.data[0]
print(page.mission_id)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Start a run
Start a new run for a mission
POST /ai/missions/{mission_id}/runs
Optional: input (object), metadata (object)
run = client.ai.missions.runs.create(
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(run.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Get run details
Get details of a specific run
GET /ai/missions/{mission_id}/runs/{run_id}
run = client.ai.missions.runs.retrieve(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(run.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Update run
Update run status and/or result
PATCH /ai/missions/{mission_id}/runs/{run_id}
Optional: error (string), metadata (object), result_payload (object), result_summary (string), status (enum: pending, running, paused, succeeded, failed, cancelled)
run = client.ai.missions.runs.update(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(run.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Cancel run
Cancel a running or paused run
POST /ai/missions/{mission_id}/runs/{run_id}/cancel
response = client.ai.missions.runs.cancel_run(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
List events
List events for a run (paginated)
GET /ai/missions/{mission_id}/runs/{run_id}/events
page = client.ai.missions.runs.events.list(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
page = page.data[0]
print(page.event_id)
Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)
Log event
Log an event for a run
POST /ai/missions/{mission_id}/runs/{run_id}/events — Required: type, summary
Optional: agent_id (string), idempotency_key (string), payload (object), step_id (string)
response = client.ai.missions.runs.events.log(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
summary="Brief task summary",
type="status_change",
)
print(response.data)
Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)
Get event details
Get details of a specific event
GET /ai/missions/{mission_id}/runs/{run_id}/events/{event_id}
response = client.ai.missions.runs.events.get_event_details(
event_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: agent_id (string), event_id (string), idempotency_key (string), payload (object), run_id (string), step_id (string), summary (string), timestamp (date-time), type (enum: status_change, step_started, step_completed, step_failed, tool_call, tool_result, message, error, custom)
Pause run
Pause a running run
POST /ai/missions/{mission_id}/runs/{run_id}/pause
response = client.ai.missions.runs.pause_run(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
Get plan
Get the plan (all steps) for a run
GET /ai/missions/{mission_id}/runs/{run_id}/plan
plan = client.ai.missions.runs.plan.retrieve(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(plan.data)
Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)
Create initial plan
Create the initial plan for a run
POST /ai/missions/{mission_id}/runs/{run_id}/plan — Required: steps
plan = client.ai.missions.runs.plan.create(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
steps=[{
"description": "description",
"sequence": 0,
"step_id": "step_id",
}],
)
print(plan.data)
Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)
Add step(s) to plan
Add one or more steps to an existing plan
POST /ai/missions/{mission_id}/runs/{run_id}/plan/steps — Required: steps
response = client.ai.missions.runs.plan.add_steps_to_plan(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
steps=[{
"description": "description",
"sequence": 0,
"step_id": "step_id",
}],
)
print(response.data)
Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)
Get step details
Get details of a specific plan step
GET /ai/missions/{mission_id}/runs/{run_id}/plan/steps/{step_id}
response = client.ai.missions.runs.plan.get_step_details(
step_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)
Update step status
Update the status of a plan step
PATCH /ai/missions/{mission_id}/runs/{run_id}/plan/steps/{step_id}
Optional: metadata (object), status (enum: pending, in_progress, completed, skipped, failed)
response = client.ai.missions.runs.plan.update_step(
step_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: completed_at (date-time), description (string), metadata (object), parent_step_id (string), run_id (uuid), sequence (integer), started_at (date-time), status (enum: pending, in_progress, completed, skipped, failed), step_id (string)
Resume run
Resume a paused run
POST /ai/missions/{mission_id}/runs/{run_id}/resume
response = client.ai.missions.runs.resume_run(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(response.data)
Returns: error (string), finished_at (date-time), input (object), metadata (object), mission_id (uuid), result_payload (object), result_summary (string), run_id (uuid), started_at (date-time), status (enum: pending, running, paused, succeeded, failed, cancelled), updated_at (date-time)
List linked Telnyx agents
List all Telnyx agents linked to a run
GET /ai/missions/{mission_id}/runs/{run_id}/telnyx-agents
telnyx_agents = client.ai.missions.runs.telnyx_agents.list(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
print(telnyx_agents.data)
Returns: created_at (date-time), run_id (string), telnyx_agent_id (string)
Link Telnyx agent to run
Link a Telnyx AI agent (voice/messaging) to a run
POST /ai/missions/{mission_id}/runs/{run_id}/telnyx-agents — Required: telnyx_agent_id
response = client.ai.missions.runs.telnyx_agents.link(
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
telnyx_agent_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response.data)
Returns: created_at (date-time), run_id (string), telnyx_agent_id (string)
Unlink Telnyx agent
Unlink a Telnyx agent from a run
DELETE /ai/missions/{mission_id}/runs/{run_id}/telnyx-agents/{telnyx_agent_id}
client.ai.missions.runs.telnyx_agents.unlink(
telnyx_agent_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
run_id="182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e",
)
List tools
List all tools for a mission
GET /ai/missions/{mission_id}/tools
response = client.ai.missions.tools.list_tools(
"mission_id",
)
print(response)
Create tool
Create a new tool for a mission
POST /ai/missions/{mission_id}/tools
response = client.ai.missions.tools.create_tool(
"mission_id",
)
print(response)
Get tool
Get a specific tool by ID
GET /ai/missions/{mission_id}/tools/{tool_id}
response = client.ai.missions.tools.get_tool(
tool_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Update tool
Update a tool definition
PUT /ai/missions/{mission_id}/tools/{tool_id}
response = client.ai.missions.tools.update_tool(
tool_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)
print(response)
Delete tool
Delete a tool from a mission
DELETE /ai/missions/{mission_id}/tools/{tool_id}
client.ai.missions.tools.delete_tool(
tool_id="550e8400-e29b-41d4-a716-446655440000",
mission_id="550e8400-e29b-41d4-a716-446655440000",
)