# Tasks

## Get Task

> Get task state by ID. Requires workspace context — the task's workspace\_id must match.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"TaskStateResponse":{"properties":{"task_id":{"type":"string","title":"Task Id"},"call_sid":{"type":"string","title":"Call Sid"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"skill":{"type":"string","title":"Skill"},"tier":{"type":"string","enum":["direct","companion","desktop","computer_use"],"title":"Tier"},"status":{"type":"string","enum":["pending","dispatched","running","completed","failed","cancelled","timeout"],"title":"Status"},"result":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"error_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Type"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Ms"},"input_tokens":{"type":"integer","title":"Input Tokens","default":0},"output_tokens":{"type":"integer","title":"Output Tokens","default":0},"cached_tokens":{"type":"integer","title":"Cached Tokens","default":0},"sub_tool_count":{"type":"integer","title":"Sub Tool Count","default":0},"progress_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Progress Message"},"progress_step":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Step"},"dispatched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dispatched At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["task_id","call_sid","workspace_id","skill","tier","status"],"title":"TaskStateResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/tasks/{task_id}":{"get":{"tags":["Tasks"],"summary":"Get Task","description":"Get task state by ID. Requires workspace context — the task's workspace_id must match.","operationId":"get_task_v1__workspace_id__tasks__task_id__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"task_id","in":"path","required":true,"schema":{"type":"string","title":"Task Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskStateResponse"}}}},"404":{"description":"Task not found or expired"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```

## List Tasks By Call

> List all tasks for a call. Only returns tasks matching the current workspace.

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"TaskListResponse":{"properties":{"tasks":{"items":{"$ref":"#/components/schemas/TaskStateResponse"},"type":"array","title":"Tasks"}},"type":"object","required":["tasks"],"title":"TaskListResponse"},"TaskStateResponse":{"properties":{"task_id":{"type":"string","title":"Task Id"},"call_sid":{"type":"string","title":"Call Sid"},"workspace_id":{"type":"string","format":"uuid","title":"Workspace Id"},"skill":{"type":"string","title":"Skill"},"tier":{"type":"string","enum":["direct","companion","desktop","computer_use"],"title":"Tier"},"status":{"type":"string","enum":["pending","dispatched","running","completed","failed","cancelled","timeout"],"title":"Status"},"result":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result"},"error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error"},"error_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Type"},"duration_ms":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Duration Ms"},"input_tokens":{"type":"integer","title":"Input Tokens","default":0},"output_tokens":{"type":"integer","title":"Output Tokens","default":0},"cached_tokens":{"type":"integer","title":"Cached Tokens","default":0},"sub_tool_count":{"type":"integer","title":"Sub Tool Count","default":0},"progress_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Progress Message"},"progress_step":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Progress Step"},"dispatched_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Dispatched At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"}},"type":"object","required":["task_id","call_sid","workspace_id","skill","tier","status"],"title":"TaskStateResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/tasks/by-call/{call_sid}":{"get":{"tags":["Tasks"],"summary":"List Tasks By Call","description":"List all tasks for a call. Only returns tasks matching the current workspace.","operationId":"list_tasks_by_call_v1__workspace_id__tasks_by_call__call_sid__get","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"call_sid","in":"path","required":true,"schema":{"type":"string","title":"Call Sid"}}],"responses":{"200":{"description":"List of tasks (may be empty)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/TaskListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}}}
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/tasks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.