Quick start

The Twin API enables you to build advanced agents with complex logic, by creating sequences of tasks, batch of tasks, conditional tasks and by composing tasks with each others - similar to how humans execute complex tasks.

Get your API Key

Sign up on our Playground and create a new API key. Remember, your API key is your access secret—keep it safe with environment variables.

Install package

Install the requests python package necessary to run the API.

pip install requests

Launch and monitor your first task

Use the following Python code to create a task and monitor the agent’s progress while completing the task

import requests
import time

api_key = "YOUR_API_KEY"
api_url = "https://api.twin.so"

# Task configuration
start_url = "https://www.google.com"
goal = "Find the latest price of AAPL stock. Return the stock price, nothing else."

# Start the task
response = requests.post(
    f"{api_url}/browse",
    headers={
        'Content-Type': 'application/json',
        'x-api-key': api_key
    },
    json={
        "startUrl": start_url,
        "goal": goal,
        "outputType": "string"
    }
)

# Get the task ID
task_id = response.json().get("taskId")
if not task_id:
    print("Failed to start task.")
    exit()

print(f"Started task with ID: {task_id}")

previous_action = None

# Poll for task status
while True:
    response = requests.get(
        f"{api_url}/task/{task_id}?limit=1",
        headers={'x-api-key': api_key}
    )
    
    data = response.json()
    
    status = data.get('status')
    steps = data.get('steps', [])
    
    if steps:
        last_action = steps[-1].get('action')
        if last_action != previous_action and last_action is not None:
            print(f"Last action: {last_action}")
            previous_action = last_action
    
    if status in ['COMPLETED', 'FAILED']:
        print(f"Task {status}.")
        break
    
    time.sleep(2)

Output Example

Started task with ID: 90347816-e2b3-479a-a28e-8b3a96f84916

Last action: 
  { 
  'action': 'type_and_submit', 
  'human_readable': 'the agent typed the text "AAPL stock price" and pressed enter in element with the id="typable-element-11" of an HTML type "textarea" and the textual content ""'
  }

Last action: 
  {
  'action': 'record', 
  'human_readable': 'Recording the following:\nThe latest price of AAPL (Apple Inc) stock is 220.82 USD.'
  }

Task COMPLETED.