Telnyx Missions Python

<!-- Auto-generated from Telnyx OpenAPI specs. Do not edit. -->

Telnyx Missions - Python

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:

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)