Python SDK

Installation

pip install --upgrade asteroid-odyssey

Create your Python file (run_agent.py)

from asteroid_odyssey import AsteroidClient

# Create client and execute agent
client = AsteroidClient('your-api-key')

execution_id = client.execute_agent(
    agent_id='your-agent-id',
    execution_data={'input': 'your data'}
)

# Wait for result
result = client.wait_for_execution_result(execution_id)
print(result)

Run the agent

Replace your API key, your agent_id, and update the execution_data with your agent’s variables (or remove if no variables), then run:

python run_agent.py

Agent Creation: Agents can only be created through the Asteroid Platform web interface. The API is designed for executing existing agents, not creating them.

Method Reference

Method	Purpose	Returns
`execute_agent()`	Start agent execution	`execution_id`
`wait_for_execution_result()`	Wait for completion	`result`
`get_execution_status()`	Check current status	`status_info`
`get_execution_result()`	Get final result	`result`
`upload_execution_files()`	Upload files	`upload_response`
`get_browser_session_recording()`	Get recording URL	`url`
`get_agent_profiles()`	Get list of agent profiles	`list`
`get_agent_profile()`	Get agent profile by ID	`profile`
`create_agent_profile()`	Create new agent profile	`profile`
`update_agent_profile()`	Update existing agent profile	`profile`
`delete_agent_profile()`	Delete agent profile	`string`

Python Examples

Comprehensive examples including file uploads, error handling, and real-world workflows

API Reference

Complete API documentation with all available endpoints

Core Methods

execute_agent() - Execute an agent with the provided parameters

Execute an agent with the provided parameters.Parameters:

agent_id: The ID of the agent to execute
execution_data: The execution parameters
agent_profile_id: Optional ID of the agent profile

Returns: The execution IDRaises:

Exception: If the execution request fails

execution_id = client.execute_agent('my-agent-id', {'input': 'some dynamic value'}, 'agent-profile-id')

get_execution_status() - Get the current status for an execution

Get the current status for an execution.Parameters:

execution_id: The execution identifier

Returns: The execution status detailsRaises:

Exception: If the status request fails

status = client.get_execution_status(execution_id)
print(status.status)

get_execution_result() - Get the final result of an execution

Get the final result of an execution.Parameters:

execution_id: The execution identifier

Returns: The result object of the executionRaises:

Exception: If the result request fails or execution failed

result = client.get_execution_result(execution_id)
print(result)

wait_for_execution_result() - Wait for an execution to reach a terminal state and return the result

Wait for an execution to reach a terminal state and return the result. Continuously polls the execution status until it’s either “completed”, “cancelled”, or “failed”.Parameters:

execution_id: The execution identifier
interval: Polling interval in seconds (default is 1.0)
timeout: Maximum wait time in seconds (default is 3600 - 1 hour)

Returns: The execution result if completedRaises:

Exception: If the execution ends as “cancelled” or “failed”, or times out

result = client.wait_for_execution_result(execution_id, interval=2.0)

upload_execution_files() - Upload files to an execution

Upload files to an execution.Parameters:

execution_id: The execution identifier
files: List of files to upload. Each file can be:
default_filename: Default filename to use when file is provided as bytes

Returns: The upload response containing message and file IDsRaises:

Exception: If the upload request fails

# Upload with file content (file should be in your current working directory)
with open('hello.txt', 'r') as f:
file_content = f.read()
response = client.upload_execution_files(execution_id, [file_content.encode()])
print(f"Uploaded files: {response.file_ids}")
# Upload with filename and content
files = [('hello.txt', file_content.encode())]
response = client.upload_execution_files(execution_id, files)
# Or create content directly
hello_content = "Hello World!".encode()
response = client.upload_execution_files(execution_id, [hello_content])

get_browser_session_recording() - Get the browser session recording URL for a completed execution

Get the browser session recording URL for a completed execution.Parameters:

execution_id: The execution identifier

Returns: The URL of the browser session recordingRaises:

Exception: If the recording request fails

recording_url = client.get_browser_session_recording(execution_id)
print(f"Recording available at: {recording_url}")

get_agent_profiles() - Get a list of agent profiles for a specific organization

Get a list of agent profiles for a specific organization.Parameters:

organization_id: The organization identifier (required)

Returns: A list of agent profilesRaises:

Exception: If the agent profiles request fails

profiles = client.get_agent_profiles("org-123")

get_agent_profile() - Get an agent profile by ID

Get an agent profile by ID.Parameters:

profile_id: The ID of the agent profile

Returns: The agent profileRaises:

Exception: If the agent profile request fails

profile = client.get_agent_profile("profile_id")

create_agent_profile() - Create an agent profile

Create an agent profile.Parameters:

request: The request object

Returns: The agent profileRaises:

Exception: If the agent profile creation fails

request = CreateAgentProfileRequest(
name="My Agent Profile",
description="This is my agent profile",
organization_id="org-123",
proxy_cc=CountryCode.US,
proxy_type=ProxyType.RESIDENTIAL,
captcha_solver_active=True,
sticky_ip=True,
credentials=[Credential(name="user", data="password")]
)
profile = client.create_agent_profile(request)

update_agent_profile() - Update an agent profile with the provided request

Update an agent profile with the provided request.Parameters:

profile_id: The ID of the agent profile
request: The request object

Returns: The agent profileRaises:

Exception: If the agent profile update fails

request = UpdateAgentProfileRequest(
name="My Agent Profile",
description="This is my agent profile",
organization_id="org-123",
)
profile = client.update_agent_profile("profile_id", request)

delete_agent_profile() - Delete an agent profile

Delete an agent profile.Parameters:

profile_id: The ID of the agent profile

Returns: Confirmation message from the serverRaises:

Exception: If the agent profile deletion fails

response = client.delete_agent_profile("profile_id")

format_agent_profile() - Format an agent profile for nice display

format_agent_profiles_list() - Format a list of agent profiles for nice display

Get Started

Fundamentals

SDKs

Support & Security

Method Reference

Python Examples

API Reference

Core Methods

Get Started

Fundamentals

SDKs

Support & Security

​Method Reference

Python Examples

API Reference

​Core Methods

Method Reference

Core Methods