Skip to main content
POST
/
v1
/
sessions
Create Session
curl --request POST \
  --url https://api.example.com/v1/sessions
Start a new agent session on a phone. The session creates a sandboxed environment where an AI agent autonomously executes your instruction.

​
Request

curl -X POST https://api.tapkit.ai/v1/sessions \
  -H "X-API-Key: joot_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"phone_id": "abc123", "instruction": "Open Instagram and like the first 3 posts"}'

​
Request Body

{
  "phone_id": "abc123-def456",
  "instruction": "Open Instagram and like the first 3 posts"
}
FieldTypeRequiredDescription
phone_idstringYesThe phone to run the session on
instructionstringYesWhat the agent should do

​
Response

Status: 201 Created 
{
  "id": "sess_abc123",
  "phone_id": "abc123-def456",
  "instruction": "Open Instagram and like the first 3 posts",
  "status": "creating",
  "cost_usd": null,
  "duration_ms": null,
  "num_turns": null,
  "error": null,
  "created_at": "2024-01-15T10:30:00Z",
  "started_at": null,
  "completed_at": null
}

​
Response Fields

FieldTypeDescription
idstringSession identifier
phone_idstringPhone the session is running on
instructionstringThe original instruction
statusstringcreating, running, paused, completed, failed, or killed
cost_usdnumber | nullCost in USD (populated after completion)
duration_msinteger | nullDuration in milliseconds (populated after completion)
num_turnsinteger | nullNumber of agent turns (populated after completion)
errorstring | nullError message if the session failed
created_atstringISO 8601 creation timestamp
started_atstring | nullISO 8601 timestamp when the session started running
completed_atstring | nullISO 8601 timestamp when the session finished

​
Examples

​
Python

import requests

response = requests.post(
    "https://api.tapkit.ai/v1/sessions",
    headers={
        "X-API-Key": "joot_...",
        "Content-Type": "application/json"
    },
    json={
        "phone_id": "abc123",
        "instruction": "Open Instagram and like the first 3 posts"
    }
)

session = response.json()
print(f"Session {session['id']} status: {session['status']}")

​
Poll Until Complete

import time

session_id = session["id"]

while True:
    resp = requests.get(
        f"https://api.tapkit.ai/v1/sessions/{session_id}",
        headers={"X-API-Key": "joot_..."}
    )
    session = resp.json()

    if session["status"] in ("completed", "failed", "killed"):
        break

    time.sleep(2)

print(f"Done: {session['status']} in {session['duration_ms']}ms, {session['num_turns']} turns")