Executions API

The Executions API allows you to track and manage tool executions in the Kubiya platform. Every time a tool is executed by an AI Teammate, the execution details are recorded and can be queried using this API.

This playground makes API calls to Kubiya API through a secure server-side proxy. Your requests never expose your API token directly to the browser.

List Executions

Retrieve a list of tool executions based on various filters.

GET /v1/executions

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Query Parameters

Name	Type	Required	Description
`tool_id`	string	No	Filter by tool ID
`teammate_id`	string	No	Filter by teammate ID
`status`	string	No	Filter by status (`success`, `failure`, `pending`)
`limit`	number	No	Maximum number of results (default: 20)
`offset`	number	No	Pagination offset
`from_date`	string	No	Filter executions after this date (ISO format)
`to_date`	string	No	Filter executions before this date (ISO format)

Response

{
  "executions": [
    {
      "id": "exec-12345",
      "tool_id": "tool-67890",
      "teammate_id": "teammate-54321",
      "status": "success",
      "started_at": "2023-05-15T14:30:00Z",
      "completed_at": "2023-05-15T14:30:05Z",
      "duration_ms": 5000,
      "inputs": {
        "instance_id": "i-abcdef123456",
        "region": "us-west-2"
      },
      "outputs": {
        "status": "stopped",
        "message": "Instance stopped successfully"
      },
      "error": null,
      "user_id": "user-98765",
      "conversation_id": "conv-24680"
    }
  ],
  "total": 42,
  "limit": 20,
  "offset": 0
}

Get Execution Details

Retrieve detailed information about a specific execution.

GET /v1/executions/{execution_id}

Path Parameters

Name	Type	Required	Description
`execution_id`	string	Yes	ID of the execution

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Response

{
  "id": "exec-12345",
  "tool_id": "tool-67890",
  "tool_name": "stop_ec2_instance",
  "teammate_id": "teammate-54321",
  "teammate_name": "AWS Assistant",
  "status": "success",
  "started_at": "2023-05-15T14:30:00Z",
  "completed_at": "2023-05-15T14:30:05Z",
  "duration_ms": 5000,
  "inputs": {
    "instance_id": "i-abcdef123456",
    "region": "us-west-2"
  },
  "outputs": {
    "status": "stopped",
    "message": "Instance stopped successfully"
  },
  "error": null,
  "logs": [
    "Connecting to AWS...",
    "Stopping instance i-abcdef123456 in region us-west-2...",
    "Instance stopped successfully"
  ],
  "user_id": "user-98765",
  "conversation_id": "conv-24680"
}

Get Tool Executions

Retrieve a list of executions for a specific tool.

GET /v1/tools/{tool_id}/executions

Path Parameters

Name	Type	Required	Description
`tool_id`	string	Yes	ID of the tool

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Query Parameters

Name	Type	Required	Description
`status`	string	No	Filter by status (`success`, `failure`, `pending`)
`limit`	number	No	Maximum number of results (default: 20)
`offset`	number	No	Pagination offset
`from_date`	string	No	Filter executions after this date (ISO format)
`to_date`	string	No	Filter executions before this date (ISO format)

Response

{
  "executions": [
    {
      "id": "exec-12345",
      "tool_id": "tool-67890",
      "teammate_id": "teammate-54321",
      "status": "success",
      "started_at": "2023-05-15T14:30:00Z",
      "completed_at": "2023-05-15T14:30:05Z",
      "duration_ms": 5000,
      "user_id": "user-98765",
      "conversation_id": "conv-24680"
    }
  ],
  "total": 15,
  "limit": 20,
  "offset": 0
}

Get Teammate Executions

Retrieve a list of executions for a specific teammate.

GET /v1/teammates/{teammate_id}/executions

Path Parameters

Name	Type	Required	Description
`teammate_id`	string	Yes	ID of the teammate

Headers

Name	Required	Description
`Authorization`	Yes	UserKey YOUR_API_KEY

Query Parameters

Name	Type	Required	Description
`tool_id`	string	No	Filter by tool ID
`status`	string	No	Filter by status (`success`, `failure`, `pending`)
`limit`	number	No	Maximum number of results (default: 20)
`offset`	number	No	Pagination offset
`from_date`	string	No	Filter executions after this date (ISO format)
`to_date`	string	No	Filter executions before this date (ISO format)

Response

{
  "executions": [
    {
      "id": "exec-12345",
      "tool_id": "tool-67890",
      "tool_name": "stop_ec2_instance",
      "teammate_id": "teammate-54321",
      "status": "success",
      "started_at": "2023-05-15T14:30:00Z",
      "completed_at": "2023-05-15T14:30:05Z",
      "duration_ms": 5000,
      "user_id": "user-98765",
      "conversation_id": "conv-24680"
    }
  ],
  "total": 38,
  "limit": 20,
  "offset": 0
}

Example Usage

List Recent Executions

# Get the last 10 successful executions
curl -X GET "https://api.kubiya.ai/v1/executions?status=success&limit=10" \
  -H "Authorization: UserKey YOUR_API_KEY"

Get Execution Details

# Get details for a specific execution
curl -X GET "https://api.kubiya.ai/v1/executions/exec-12345" \
  -H "Authorization: UserKey YOUR_API_KEY"

Get Tool Executions

# Get executions for a specific tool in the last week
curl -X GET "https://api.kubiya.ai/v1/tools/tool-67890/executions?from_date=2023-05-10T00:00:00Z" \
  -H "Authorization: UserKey YOUR_API_KEY"

Get Teammate Executions

# Get failed executions for a specific teammate
curl -X GET "https://api.kubiya.ai/v1/teammates/teammate-54321/executions?status=failure" \
  -H "Authorization: UserKey YOUR_API_KEY"

The Executions API is useful for monitoring tool usage, troubleshooting issues, and gathering analytics about how your AI Teammates are performing various tasks.

Common Errors

HTTP Status	Description
400	Bad Request - Invalid parameters or filters
401	Unauthorized - API key is missing or invalid
403	Forbidden - The API key doesn't have permission to access these executions
404	Not Found - The specified execution, tool, or teammate was not found
500	Internal Server Error - An unexpected error occurred on the server

Next Steps

After analyzing executions, you can:

Use insights to improve your tools
Adjust teammate configurations based on execution patterns
Set up webhooks to automatically respond to execution events

Executions API

On this page