Skip to main content
GET
/
v1
/
sessions
/
{session_id}
/
status
Get Execution Status
curl --request GET \
  --url https://api.example.com/v1/sessions/{session_id}/status \
  --header 'Authorization: <authorization>'
{
  "status": "running"
}

​
Overview

Returns the current execution status of the agent. This is a lightweight endpoint perfect for polling to check if a task is complete.
This endpoint returns execution status (task state), not session status (lifecycle state). See the Get Session endpoint for session status.

​
Request

​
session_id
string
required
The UUID of the session
​
Authorization
string
required
Bearer token for authentication

​
Response

​
status
string
required
Current execution statusPossible values:
  • running - Agent is actively executing a task
  • waiting_for_input - Agent is waiting for user response to a question
  • finished - Task completed successfully
  • error - Task encountered an error
{
  "status": "running"
}

​
Example Requests

import { AGIClient } from 'agi';

const client = new AGIClient({ apiKey: 'your_api_key' });

// Get status
const status = await client.getStatus(sessionId);
console.log(`Status: ${status.status}`);

// Poll until completion
async function waitForCompletion(sessionId, pollInterval = 2000) {
  while (true) {
    const data = await client.getStatus(sessionId);
    console.log(`Status: ${data.status}`);
    
    if (['finished', 'error'].includes(data.status)) {
      return data.status;
    }
    
    if (data.status === 'waiting_for_input') {
      console.log('Agent needs your input');
      return data.status;
    }
    
    await new Promise(resolve => setTimeout(resolve, pollInterval));
  }
}

​
Status Flow

​
Use Cases

​
Simple Polling Loop

# Check status every 2 seconds
while True:
    status = get_status(session_id)
    if status in ["finished", "error"]:
        break
    time.sleep(2)

​
Conditional Logic

status = get_status(session_id)

if status == "waiting_for_input":
    # Agent has a question - check messages
    messages = get_messages(session_id)
    # ... handle question
elif status == "finished":
    # Task complete - fetch final results
    messages = get_messages(session_id)
elif status == "error":
    # Handle error
    print("Task failed")

​
Progress Updates

def monitor_with_updates(session_id):
    start_time = time.time()

    while True:
        status = get_status(session_id)
        elapsed = int(time.time() - start_time)

        print(f"[{elapsed}s] Status: {status}")

        if status in ["finished", "error"]:
            break

        time.sleep(3)

​
Status vs Session State

Execution StatusMeaningSession Status
runningTask in progressrunning
waiting_for_inputNeeds user inputrunning
finishedTask completerunning or completed
errorTask failederror
A session can be running (lifecycle) while execution is waiting_for_input or finished. Use execution status to track task progress, not session status.

​
Best Practices

Use this endpoint for simple status checks. It’s more efficient than fetching full messages when you just need to know if the task is done.
Recommended polling interval: 1-3 seconds. More frequent polling is generally unnecessary.
Always handle the waiting_for_input status - the agent may need your response to continue.