Tasks API
API endpoints for managing tasks in the Kubiya platform
Tasks API
The Tasks API allows you to manage tasks in your organization, including creating, monitoring, and controlling task execution. Tasks represent units of work that can be executed by runners and agents.
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.
Endpoints
Method | Path | Description |
---|---|---|
GET | /api/v1/tasks | List all tasks |
GET | /api/v1/tasks/{taskId} | Get task details |
POST | /api/v1/tasks | Create a new task |
PUT | /api/v1/tasks/{taskId}/cancel | Cancel a task |
GET | /api/v1/tasks/{taskId}/logs | Get task logs |
GET | /api/v1/tasks/{taskId}/status | Get task status |
GET | /api/v1/tasks/agent/{agentId} | List tasks for an agent |
GET | /api/v1/tasks/runner/{runnerId} | List tasks for a runner |
Common Response Status Codes
Status Code | Description |
---|---|
200 | Success |
400 | Bad Request - Invalid parameters or request body |
401 | Unauthorized - Invalid or missing API key |
403 | Forbidden - Insufficient permissions |
404 | Not Found - Resource doesn't exist |
500 | Internal Server Error |
Error Response Format
List Tasks
Retrieve all tasks in your organization.
Query Parameters
Name | Type | Required | Description |
---|---|---|---|
status | string | No | Filter by task status |
agent | string | No | Filter by agent ID |
runner | string | No | Filter by runner ID |
limit | integer | No | Maximum number of tasks to return (default: 50) |
page | integer | No | Page number for pagination |
sort | string | No | Sort by field (created_at, updated_at, status) |
order | string | No | Sort order (asc, desc) |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
Get Task Details
Retrieve details for a specific task.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
taskId | string | Yes | ID of the task |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
Create Task
Create a new task.
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Content-Type | Yes | application/json |
Request Body
Required Fields
name
: Name of the taskagent_id
: ID of the agent to execute the taskrunner_id
: ID of the runner to use
Response
Cancel Task
Cancel a running task.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
taskId | string | Yes | ID of the task to cancel |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
Get Task Logs
Retrieve logs for a specific task.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
taskId | string | Yes | ID of the task |
Query Parameters
Name | Type | Required | Description |
---|---|---|---|
start_time | string | No | Filter logs after this timestamp |
end_time | string | No | Filter logs before this timestamp |
level | string | No | Filter by log level (info, error, debug) |
limit | integer | No | Maximum number of log entries to return |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
Get Task Status
Get the current status of a task.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
taskId | string | Yes | ID of the task |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
List Tasks for Agent
Retrieve all tasks associated with a specific agent.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
agentId | string | Yes | ID of the agent |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
List Tasks for Runner
Retrieve all tasks associated with a specific runner.
Path Parameters
Name | Type | Required | Description |
---|---|---|---|
runnerId | string | Yes | ID of the runner |
Headers
Name | Required | Description |
---|---|---|
Authorization | Yes | UserKey YOUR_API_KEY |
Response
Tasks are the core unit of work in the Kubiya platform. Monitor task execution and logs to ensure successful operations.
Example Usage
Common Errors
HTTP Status | Description |
---|---|
400 | Bad Request - Invalid request body or missing required fields |
401 | Unauthorized - API key is missing or invalid |
403 | Forbidden - The API key doesn't have permission to perform this action |
404 | Not Found - The specified task was not found |
409 | Conflict - Task is in an invalid state for the requested operation |
500 | Internal Server Error - An unexpected error occurred on the server |
Next Steps
After managing tasks, you can: