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://cc.teamday.ai/api/v1/executions

Authentication: Personal Access Token required

Endpoints Overview

Method	Endpoint	Description	Status
GET	`/executions`	List executions	🟡 Untested
GET	`/executions/[id]`	Get execution details	🟡 Untested
GET	`/executions/[id]/tree`	Get execution tree (subagents)	🟡 Untested
POST	`/executions/[id]/cancel`	Cancel running execution	🟡 Untested

Implementation Status: Complete but untested in production

Execution Object

Properties

{
  id: string              // Execution ID (format: exec_xxx)
  agentId: string         // Agent that executed
  organizationId: string  // Owner organization
  userId: string          // User who triggered execution
  status: string          // "pending" | "running" | "completed" | "failed" | "cancelled"
  startedAt: string       // ISO 8601 timestamp
  completedAt?: string    // ISO 8601 timestamp (if finished)
  messages: Message[]     // Conversation history
  toolCalls: ToolCall[]   // Tools used during execution
  error?: string          // Error message (if failed)
  metadata: object        // Additional execution context
}

Example Object

{
  "id": "exec_xyz789",
  "agentId": "agent_abc123",
  "organizationId": "org_456",
  "userId": "user_789",
  "status": "completed",
  "startedAt": "2025-12-09T10:30:00Z",
  "completedAt": "2025-12-09T10:30:45Z",
  "messages": [
    {
      "role": "user",
      "content": "Analyze this sales data",
      "timestamp": "2025-12-09T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "Based on the sales data analysis...",
      "timestamp": "2025-12-09T10:30:45Z"
    }
  ],
  "toolCalls": [
    {
      "tool": "read_file",
      "arguments": { "path": "sales_data.csv" },
      "result": "Success",
      "timestamp": "2025-12-09T10:30:20Z"
    }
  ],
  "metadata": {
    "model": "claude-3-5-sonnet-20241022",
    "tokensUsed": 1234,
    "duration": 45000
  }
}

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):

[
  {
    "id": "exec_xyz789",
    "agentId": "agent_abc123",
    "organizationId": "org_456",
    "userId": "user_789",
    "status": "completed",
    "startedAt": "2025-12-09T10:30:00Z",
    "completedAt": "2025-12-09T10:30:45Z",
    "metadata": {
      "model": "claude-3-5-sonnet-20241022",
      "duration": 45000
    }
  },
  {
    "id": "exec_abc456",
    "agentId": "agent_abc123",
    "organizationId": "org_456",
    "userId": "user_789",
    "status": "running",
    "startedAt": "2025-12-09T11:00:00Z",
    "metadata": {
      "model": "claude-3-5-sonnet-20241022"
    }
  }
]

Empty result:

[]

Error (401 Unauthorized):

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

Examples

List all executions:

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

Filter by agent:

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

Limit results:

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

Combine filters:

curl "https://cc.teamday.ai/api/v1/executions?agentId=agent_abc123&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_xxx)

Response

Success (200 OK):

{
  "id": "exec_xyz789",
  "agentId": "agent_abc123",
  "organizationId": "org_456",
  "userId": "user_789",
  "status": "completed",
  "startedAt": "2025-12-09T10:30:00Z",
  "completedAt": "2025-12-09T10:30:45Z",
  "messages": [
    {
      "role": "user",
      "content": "Analyze this sales data and provide insights",
      "timestamp": "2025-12-09T10:30:00Z"
    },
    {
      "role": "assistant",
      "content": "I'll analyze the sales data for you. Let me read the file first.",
      "timestamp": "2025-12-09T10:30:05Z"
    },
    {
      "role": "tool",
      "content": "File read successfully: 1234 rows of sales data",
      "timestamp": "2025-12-09T10:30:20Z"
    },
    {
      "role": "assistant",
      "content": "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",
      "timestamp": "2025-12-09T10:30:45Z"
    }
  ],
  "toolCalls": [
    {
      "tool": "read_file",
      "arguments": {
        "path": "sales_data.csv"
      },
      "result": "Success",
      "timestamp": "2025-12-09T10:30:20Z"
    }
  ],
  "metadata": {
    "model": "claude-3-5-sonnet-20241022",
    "tokensUsed": 2847,
    "duration": 45000,
    "toolsUsed": ["read_file"]
  }
}

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": "Invalid or expired token"
}

Example

curl https://cc.teamday.ai/api/v1/executions/exec_xyz789 \
  -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_xxx)

Response

Success (200 OK):

{
  "root": {
    "id": "exec_parent123",
    "agentId": "agent_orchestrator",
    "status": "completed",
    "startedAt": "2025-12-09T10:00:00Z",
    "completedAt": "2025-12-09T10:05:00Z"
  },
  "children": [
    {
      "id": "exec_child456",
      "agentId": "agent_researcher",
      "parentExecutionId": "exec_parent123",
      "status": "completed",
      "startedAt": "2025-12-09T10:00:30Z",
      "completedAt": "2025-12-09T10:02:00Z",
      "children": []
    },
    {
      "id": "exec_child789",
      "agentId": "agent_writer",
      "parentExecutionId": "exec_parent123",
      "status": "completed",
      "startedAt": "2025-12-09T10:02:30Z",
      "completedAt": "2025-12-09T10:05:00Z",
      "children": []
    }
  ],
  "metadata": {
    "totalExecutions": 3,
    "maxDepth": 2,
    "totalDuration": 300000
  }
}

Single execution (no subagents):

{
  "root": {
    "id": "exec_xyz789",
    "agentId": "agent_abc123",
    "status": "completed",
    "startedAt": "2025-12-09T10:30:00Z",
    "completedAt": "2025-12-09T10:30:45Z"
  },
  "children": [],
  "metadata": {
    "totalExecutions": 1,
    "maxDepth": 1,
    "totalDuration": 45000
  }
}

Error (404 Not Found):

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

Example

curl https://cc.teamday.ai/api/v1/executions/exec_parent123/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_xxx)

Body: None

Response

Success (200 OK):

{
  "success": true,
  "message": "Execution cancelled successfully",
  "execution": {
    "id": "exec_xyz789",
    "status": "cancelled",
    "cancelledAt": "2025-12-09T10:35:00Z"
  }
}

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://cc.teamday.ai/api/v1/executions/exec_xyz789/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://cc.teamday.ai/api/v1/executions?agentId=agent_abc123" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

By Status (Future)

Coming soon: Filter by execution status

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

Pagination

Control result count:

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

# Get up to 100 executions
curl "https://cc.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://cc.teamday.ai/api/v1/executions?limit=50&offset=50" \
  -H "Authorization: Bearer $TEAMDAY_TOKEN"

Performance Metrics

Execution metadata includes performance data:

Duration

Field: metadata.duration (milliseconds)

Calculation: completedAt - startedAt

Use cases:

Track average agent response time
Identify slow executions
Optimize agent prompts

Token Usage

Field: metadata.tokensUsed (number)

Description: Total tokens consumed (input + output)

Use cases:

Estimate API costs
Optimize prompt length
Monitor token efficiency

Model

Field: metadata.model (string)

Example: "claude-3-5-sonnet-20241022"

Use cases:

Track which models are used
Compare performance across models
Audit model selection

Tools Used

Field: metadata.toolsUsed (string array)

Example: ["read_file", "write_file", "bash"]

Use cases:

Understand agent behavior
Track tool usage patterns
Debug tool-related issues

Common Patterns

Monitor Running Executions

Poll for running executions to monitor agent activity:

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

  const executions = await response.json()

  return 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://cc.teamday.ai/api/v1/executions?agentId=${agentId}&limit=100`,
    {
      headers: {
        'Authorization': `Bearer ${process.env.TEAMDAY_TOKEN}`
      }
    }
  )

  const executions = await response.json()

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

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

  const avgTokens = completed.reduce((sum, e) => {
    return sum + (e.metadata.tokensUsed || 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://cc.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://cc.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://cc.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
    }
  }
}