Executions API

Executions represent instances when agents run. Each execution captures the complete history of messages, tool usage, results, and performance metrics. Use the Executions API to monitor agent activity, track task completion, and analyze execution patterns.

Base URL: https://us.teamday.ai/api/v1/executions

Authentication: Personal Access Token required

Endpoints Overview

MethodEndpointDescriptionStatus
GET/executionsList executions🟡 Untested
GET/executions/[id]Get execution details🟡 Untested
GET/executions/[id]/treeGet execution tree (subagents)🟡 Untested
POST/executions/[id]/cancelCancel running execution🟡 Untested

Implementation Status: Complete but untested in production

Execution Object

Properties

{
  id: string              // Execution ID (format: exec-{timestamp}-{random})
  agentId: string         // Agent that executed
  organizationId: string  // Owner organization
  userId?: string         // User who triggered execution
  chatId: string          // Associated chat ID
  sessionId: string       // Claude Code session ID
  status: string          // "pending" | "running" | "completed" | "failed" | "cancelled"
  message: string         // User's message (singular)
  result?: string         // Agent's response
  error?: string          // Error message (if failed)
  agentName?: string      // Agent display name (for notifications)
  parentExecutionId?: string  // Parent execution (if delegated)
  delegationDepth: number // Depth in delegation chain
  startedAt: string       // ISO 8601 timestamp
  completedAt?: string    // ISO 8601 timestamp (if finished)
  duration?: number       // Milliseconds
  tokensInput?: number    // Input tokens used
  tokensOutput?: number   // Output tokens used
  cost?: number           // Execution cost
}

Example Object

{
  "id": "exec-1734567890-abc",
  "agentId": "abc123def456",
  "organizationId": "org_456",
  "userId": "user_789",
  "chatId": "chat_abc123",
  "sessionId": "session_xyz789",
  "status": "completed",
  "message": "Analyze this sales data",
  "result": "Based on the sales data analysis, revenue increased 23% YoY...",
  "agentName": "Research Assistant",
  "delegationDepth": 0,
  "startedAt": "2025-12-09T10:30:00Z",
  "completedAt": "2025-12-09T10:30:45Z",
  "duration": 45000,
  "tokensInput": 856,
  "tokensOutput": 378,
  "cost": 0.0045
}

List Executions

Retrieve execution history for your organization, optionally filtered by agent.

Request

GET /api/v1/executions

Headers:

Authorization: Bearer td_xxxxx...

Query Parameters:

  • agentId (string, optional) - Filter by specific agent
  • limit (number, optional) - Maximum results (default: 50, max: 100)

Response

Success (200 OK):

{
  "success": true,
  "executions": [
    {
      "id": "exec-1734567890-abc",
      "agentId": "abc123def456",
      "organizationId": "org_456",
      "userId": "user_789",
      "chatId": "chat_abc123",
      "sessionId": "session_xyz789",
      "status": "completed",
      "message": "Analyze this sales data",
      "result": "Based on the sales data analysis...",
      "delegationDepth": 0,
      "startedAt": "2025-12-09T10:30:00Z",
      "completedAt": "2025-12-09T10:30:45Z",
      "duration": 45000,
      "tokensInput": 856,
      "tokensOutput": 378,
      "cost": 0.0045
    },
    {
      "id": "exec-1734571200-def",
      "agentId": "abc123def456",
      "organizationId": "org_456",
      "userId": "user_789",
      "chatId": "chat_def456",
      "sessionId": "session_abc123",
      "status": "running",
      "message": "Generate weekly report",
      "delegationDepth": 0,
      "startedAt": "2025-12-09T11:00:00Z"
    }
  ]
}

Empty result:

{
  "success": true,
  "executions": []
}

Error (401 Unauthorized):

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Unauthorized. Invalid or expired token"
}

Examples

List all executions:

curl https://us.teamday.ai/api/v1/executions \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Filter by agent:

curl "https://us.teamday.ai/api/v1/executions?agentId=abc123def456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Limit results:

curl "https://us.teamday.ai/api/v1/executions?limit=10" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Combine filters:

curl "https://us.teamday.ai/api/v1/executions?agentId=abc123def456&limit=25" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Get Execution Details

Retrieve complete details for a specific execution, including full message history and tool calls.

Request

GET /api/v1/executions/[id]

Headers:

Authorization: Bearer td_xxxxx...

Path Parameters:

  • id (string) - Execution ID (format: exec-{timestamp}-{random})

Response

Success (200 OK):

{
  "success": true,
  "execution": {
    "id": "exec-1734567890-abc",
    "agentId": "abc123def456",
    "organizationId": "org_456",
    "userId": "user_789",
    "chatId": "chat_abc123",
    "sessionId": "session_xyz789",
    "status": "completed",
    "message": "Analyze this sales data and provide insights",
    "result": "Based on the sales data analysis:\n\n1. Revenue increased 23% YoY\n2. Top performing region: West Coast (35% of total)\n3. Q4 shows strongest growth (+42%)\n\nRecommendations:\n- Focus marketing efforts on West Coast\n- Replicate Q4 strategies in other quarters\n- Investigate underperforming regions",
    "agentName": "Research Assistant",
    "delegationDepth": 0,
    "startedAt": "2025-12-09T10:30:00Z",
    "completedAt": "2025-12-09T10:30:45Z",
    "duration": 45000,
    "tokensInput": 1523,
    "tokensOutput": 1324,
    "cost": 0.0089
  }
}

Error (404 Not Found):

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Execution not found"
}

Error (401 Unauthorized):

{
  "error": true,
  "statusCode": 401,
  "statusMessage": "Unauthorized",
  "message": "Unauthorized. Invalid or expired token"
}

Example

curl https://us.teamday.ai/api/v1/executions/exec-1734567890-abc \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Get Execution Tree

Retrieve the execution tree showing parent-child relationships when agents delegate work to subagents.

Request

GET /api/v1/executions/[id]/tree

Headers:

Authorization: Bearer td_xxxxx...

Path Parameters:

  • id (string) - Execution ID (format: exec-{timestamp}-{random})

Response

The tree response is a recursive structure: each execution object may contain a children array of the same shape (Execution & { children?: ExecutionTree[] }).

Success (200 OK):

{
  "success": true,
  "tree": {
    "id": "exec-1734567890-abc",
    "agentId": "abc123def456",
    "organizationId": "org_456",
    "chatId": "chat_abc123",
    "sessionId": "session_xyz789",
    "status": "completed",
    "message": "Research and write a report on AI trends",
    "result": "Here is the completed report...",
    "delegationDepth": 0,
    "startedAt": "2025-12-09T10:00:00Z",
    "completedAt": "2025-12-09T10:05:00Z",
    "children": [
      {
        "id": "exec-1734567920-def",
        "agentId": "ghi789jkl012",
        "organizationId": "org_456",
        "chatId": "chat_abc123",
        "sessionId": "session_xyz789",
        "status": "completed",
        "message": "Research AI trends for 2025",
        "result": "Key findings: ...",
        "parentExecutionId": "exec-1734567890-abc",
        "delegationDepth": 1,
        "startedAt": "2025-12-09T10:00:30Z",
        "completedAt": "2025-12-09T10:02:00Z",
        "children": []
      },
      {
        "id": "exec-1734568050-ghi",
        "agentId": "mno345pqr678",
        "organizationId": "org_456",
        "chatId": "chat_abc123",
        "sessionId": "session_xyz789",
        "status": "completed",
        "message": "Write the report based on research",
        "result": "Report draft completed...",
        "parentExecutionId": "exec-1734567890-abc",
        "delegationDepth": 1,
        "startedAt": "2025-12-09T10:02:30Z",
        "completedAt": "2025-12-09T10:05:00Z",
        "children": []
      }
    ]
  }
}

Single execution (no subagents):

{
  "success": true,
  "tree": {
    "id": "exec-1734567890-abc",
    "agentId": "abc123def456",
    "organizationId": "org_456",
    "chatId": "chat_abc123",
    "sessionId": "session_xyz789",
    "status": "completed",
    "message": "Analyze this sales data",
    "result": "Based on the analysis...",
    "delegationDepth": 0,
    "startedAt": "2025-12-09T10:30:00Z",
    "completedAt": "2025-12-09T10:30:45Z"
  }
}

Error (404 Not Found):

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Execution not found"
}

Example

curl https://us.teamday.ai/api/v1/executions/exec-1734567890-abc/tree \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Use Cases

Monitoring delegation:

  • Track when agents delegate to subagents
  • Measure efficiency of agent collaboration
  • Debug complex multi-agent workflows

Performance analysis:

  • Identify bottlenecks in delegated tasks
  • Compare serial vs. parallel delegation
  • Optimize agent orchestration

Cancel Execution

Stop a running execution. Only executions in pending or running status can be cancelled.

Request

POST /api/v1/executions/[id]/cancel

Headers:

Authorization: Bearer td_xxxxx...

Path Parameters:

  • id (string) - Execution ID (format: exec-{timestamp}-{random})

Body: None

Response

Success (200 OK):

{
  "success": true,
  "message": "Execution cancelled"
}

Error (400 Bad Request - Already completed):

{
  "error": true,
  "statusCode": 400,
  "statusMessage": "Bad Request",
  "message": "Cannot cancel execution: already completed"
}

Error (404 Not Found):

{
  "error": true,
  "statusCode": 404,
  "statusMessage": "Not Found",
  "message": "Execution not found"
}

Example

curl -X POST https://us.teamday.ai/api/v1/executions/exec-1734567890-abc/cancel \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Notes

Cancellation behavior:

  • Execution immediately marked as cancelled
  • Agent stops processing (best effort)
  • Partial results may be saved
  • Cannot resume cancelled execution
  • Subagents (if any) are also cancelled

When to cancel:

  • Long-running execution taking too long
  • Agent stuck in infinite loop
  • User changed requirements
  • Testing/debugging purposes

Execution Status

Executions progress through the following states:

Pending

Status: "pending"

Description: Execution created but not yet started. Waiting for resources or queued.

Duration: Usually < 1 second

Next states: running, cancelled

Running

Status: "running"

Description: Agent actively processing. May involve multiple tool calls and API requests.

Duration: Varies (seconds to minutes)

Next states: completed, failed, cancelled

Completed

Status: "completed"

Description: Execution finished successfully. Results available.

Terminal state: Yes (no further transitions)

Failed

Status: "failed"

Description: Execution encountered an error and stopped. Check error field for details.

Terminal state: Yes (no further transitions)

Common causes:

  • API errors (rate limits, service unavailable)
  • Invalid tool calls
  • Permission errors
  • Timeout

Cancelled

Status: "cancelled"

Description: Execution manually stopped via cancel endpoint.

Terminal state: Yes (no further transitions)

Filtering & Pagination

By Agent

Filter executions for a specific agent:

curl "https://us.teamday.ai/api/v1/executions?agentId=abc123def456" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

By Status (Future)

Coming soon: Filter by execution status

# Future feature
curl "https://us.teamday.ai/api/v1/executions?status=running" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Pagination

Control result count:

# Get first 10 executions
curl "https://us.teamday.ai/api/v1/executions?limit=10" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

# Get up to 100 executions
curl "https://us.teamday.ai/api/v1/executions?limit=100" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Defaults:

  • Default limit: 50
  • Maximum limit: 100
  • Results ordered by startedAt (newest first)

Offset-based pagination (Future):

# Future feature
curl "https://us.teamday.ai/api/v1/executions?limit=50&offset=50" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Performance Metrics

Execution objects include performance data directly as top-level fields:

Duration

Field: duration (milliseconds)

Calculation: completedAt - startedAt

Use cases:

  • Track average agent response time
  • Identify slow executions
  • Optimize agent prompts

Token Usage

Fields: tokensInput (number), tokensOutput (number)

Description: Input and output tokens consumed separately.

Use cases:

  • Estimate API costs
  • Optimize prompt length
  • Monitor token efficiency

Cost

Field: cost (number)

Description: Estimated cost for this execution in USD.

Use cases:

  • Budget tracking
  • Cost optimization
  • Per-agent cost analysis

Common Patterns

Monitor Running Executions

Poll for running executions to monitor agent activity:

async function getRunningExecutions() {
  const response = await fetch('https://us.teamday.ai/api/v1/executions', {
    headers: {
      'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`
    }
  })

  const data = await response.json()

  return data.executions.filter(exec => exec.status === 'running')
}

// Check every 5 seconds
setInterval(async () => {
  const running = await getRunningExecutions()
  console.log(`${running.length} executions running`)
}, 5000)

Track Agent Performance

Calculate average execution time per agent:

async function getAgentPerformance(agentId) {
  const response = await fetch(
    `https://us.teamday.ai/api/v1/executions?agentId=${agentId}&limit=100`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`
      }
    }
  )

  const data = await response.json()
  const executions = data.executions

  const completed = executions.filter(e => e.status === 'completed')

  const avgDuration = completed.reduce((sum, e) => {
    return sum + (e.duration || 0)
  }, 0) / completed.length

  const avgTokens = completed.reduce((sum, e) => {
    return sum + (e.tokensInput || 0) + (e.tokensOutput || 0)
  }, 0) / completed.length

  return {
    totalExecutions: executions.length,
    completedExecutions: completed.length,
    avgDuration: Math.round(avgDuration),
    avgTokens: Math.round(avgTokens)
  }
}

Cancel Long-Running Executions

Auto-cancel executions exceeding a timeout:

async function cancelLongRunning(timeoutMs = 300000) { // 5 minutes
  const response = await fetch('https://us.teamday.ai/api/v1/executions', {
    headers: {
      'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`
    }
  })

  const executions = await response.json()
  const now = Date.now()

  for (const exec of executions) {
    if (exec.status !== 'running') continue

    const startedAt = new Date(exec.startedAt).getTime()
    const elapsed = now - startedAt

    if (elapsed > timeoutMs) {
      console.log(`Cancelling execution ${exec.id} (running ${elapsed}ms)`)

      await fetch(`https://us.teamday.ai/api/v1/executions/${exec.id}/cancel`, {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`
        }
      })
    }
  }
}

Error Handling

Common Errors

400 Bad Request:

  • Attempting to cancel completed/failed execution
  • Invalid query parameters

401 Unauthorized:

  • Missing Authorization header
  • Invalid or expired token

404 Not Found:

  • Execution ID doesn't exist
  • Execution belongs to different organization

500 Internal Server Error:

  • Database connectivity issues
  • Service temporarily unavailable

Retry Strategy

For transient failures, implement exponential backoff:

async function getExecutionWithRetry(executionId, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      const response = await fetch(
        `https://us.teamday.ai/api/v1/executions/${executionId}`,
        {
          headers: {
            'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`
          }
        }
      )

      if (!response.ok) {
        const error = await response.json()

        // Don't retry client errors
        if (response.status >= 400 && response.status < 500) {
          throw new Error(error.message)
        }

        // Retry server errors
        if (i === maxRetries - 1) throw new Error(error.message)

        await new Promise(resolve =>
          setTimeout(resolve, Math.pow(2, i) * 1000)
        )
        continue
      }

      return await response.json()

    } catch (err) {
      if (i === maxRetries - 1) throw err
    }
  }
}

Best Practices

Monitoring

Poll frequency:

  • Running executions: 2-5 seconds
  • Completed executions: No polling needed (use webhooks when available)

What to monitor:

  • Executions stuck in running > 5 minutes
  • High failure rate (> 10%)
  • Unusual token usage spikes

Storage

Execution retention:

  • Keep recent executions (last 30 days) for debugging
  • Archive older executions for compliance
  • Delete sensitive data per retention policy

Note: TeamDay currently retains all executions indefinitely. Self-service deletion coming soon.

Performance

Optimize agent prompts:

  • Monitor tokensInput and tokensOutput to reduce costs
  • Track duration to improve response time
  • Review cost to monitor spending per execution

Parallel execution:

  • Run multiple agents concurrently (no API limits currently)
  • Use execution trees for delegation patterns
  • Monitor total active executions

Need Help?

Issues with executions?

  • Check error reference for troubleshooting
  • Monitor execution status and error messages
  • Use execution trees to debug delegation

Questions?

Last Updated: February 19, 2026