> ## Documentation Index > Fetch the complete documentation index at: https://docs.periskope.app/llms.txt > Use this file to discover all available pages before exploring further. # Get Task By ID > Looks up a task by its task_id. Responds 404 when no task matches. ## OpenAPI ````yaml api-reference/openapi-generated.json GET /v1/tasks/{task_id} openapi: 3.0.3 info: title: Periskope API version: 1.0.0 description: >- Periskope external API. Responses use a flat, unwrapped shape: most endpoints return the resource at the top level, and list endpoints return a wrapper object with pagination inline (e.g. `{ from, to, count, chats: [...] }`). The documented response schemas describe these shapes directly. servers: - url: https://api.periskope.app security: - bearerAuth: [] paths: /v1/tasks/{task_id}: get: tags: - Tasks summary: Get a task by id description: Looks up a task by its task_id. Responds 404 when no task matches. operationId: getTaskById parameters: - schema: type: string minLength: 1 description: >- Unique id of the task (task-xxxxxxxxxxxxxxxx), returned when the task was created example: task-aaaaaaaaaaaa required: true description: >- Unique id of the task (task-xxxxxxxxxxxxxxxx), returned when the task was created name: task_id in: path responses: '200': description: The task content: application/json: schema: $ref: '#/components/schemas/Task' examples: default: summary: Response body value: task_id: task-aaaaaaaaaaaa title: Call back the customer about the renewal quote type: message status: open priority: 2 assignee: user@example.com created_by: api last_updated_by: api created_at: '2026-01-15T09:30:00.000Z' last_updated_at: '2026-01-15T09:30:00.000Z' due_date: '2026-01-20T17:00:00.000Z' remind_at: '2026-01-20T09:00:00.000Z' notes: Customer prefers a call after 3pm IST chat_id: 120363000000000000@g.us association: type: message chat_id: 120363000000000000@g.us message_id: false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAA ticket_id: ACM-042 completed_metadata: completed_at: '2026-01-21T10:15:00.000Z' completed_by: user@example.com '401': description: Invalid, expired or missing API token content: application/json: examples: error: summary: Invalid, expired or missing API token value: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 schema: type: object properties: code: type: string example: UNAUTHORIZED_ERROR message: type: string example: Invalid bearer auth token status: type: integer example: 401 example: code: UNAUTHORIZED_ERROR message: Invalid bearer auth token status: 401 '404': description: No task matches task_id content: application/json: examples: error: summary: No task matches task_id value: code: NOT_FOUND_ERROR message: No task matches task_id status: 404 schema: type: object properties: code: type: string example: NOT_FOUND_ERROR message: type: string example: No task matches task_id status: type: integer example: 404 example: code: NOT_FOUND_ERROR message: No task matches task_id status: 404 '422': description: Request validation failed content: application/json: examples: error: summary: Request validation failed value: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required schema: type: object properties: code: type: string example: VALIDATION_ERROR message: type: string example: Request validation failed status: type: integer example: 422 fields: type: object additionalProperties: type: object properties: message: type: string value: {} example: body.chat_id: message: chat_id is required example: code: VALIDATION_ERROR message: Request validation failed status: 422 fields: body.chat_id: message: chat_id is required '429': description: Rate limit exceeded content: application/json: examples: error: summary: Rate limit exceeded value: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 schema: type: object properties: code: type: string example: RATE_LIMIT_ERROR message: type: string example: You can only make 100 requests per second status: type: integer example: 429 example: code: RATE_LIMIT_ERROR message: You can only make 100 requests per second status: 429 '500': description: Internal server error content: application/json: examples: error: summary: Internal server error value: code: UNKNOWN_ERROR message: Internal server error status: 500 schema: type: object properties: code: type: string example: UNKNOWN_ERROR message: type: string example: Internal server error status: type: integer example: 500 example: code: UNKNOWN_ERROR message: Internal server error status: 500 security: - bearerAuth: [] x-codeSamples: - lang: typescript label: TypeScript source: |- import { PeriskopeApi } from '@periskope/periskope-client'; const client = new PeriskopeApi({ authToken: 'YOUR_API_KEY', }); async function main() { const response = await client.tasks.getTaskById({ task_id: 'task-aaaaaaaaaaaa', }); console.log(response); } main(); - lang: bash label: cURL source: |- curl -X GET 'https://api.periskope.app/v1/tasks/task-aaaaaaaaaaaa' \ -H 'Authorization: Bearer YOUR_API_KEY' components: schemas: Task: type: object properties: task_id: type: string description: >- Unique id of the task (task-xxxxxxxxxxxxxxxx). Use this value as the task_id path parameter when fetching or updating the task. example: task-aaaaaaaaaaaa title: type: string description: Title of the task, up to 500 characters example: Call back the customer about the renewal quote type: type: string enum: - todo - chat - message - ticket description: >- Kind of task: 'todo' for a standalone task, or 'chat', 'message' or 'ticket' for a task linked to that object. Immutable after creation. example: message status: type: string enum: - open - inprogress - closed description: 'Lifecycle status of the task: ''open'', ''inprogress'' or ''closed''' example: open priority: type: integer description: 'Priority of the task: 1 (low), 2 (medium) or 3 (high)' example: 2 assignee: type: string description: >- Email of the workspace member the task is assigned to. null when the task is unassigned. example: user@example.com created_by: type: string description: >- Who created the task: a member's email, or "api" when created via the API without a created_by example: api last_updated_by: type: string description: >- Who last changed the task: a member's email, or "api" for API changes without a last_updated_by example: api created_at: type: string description: When the task was created, as an ISO 8601 timestamp example: '2026-01-15T09:30:00.000Z' last_updated_at: type: string description: When the task was last updated, as an ISO 8601 timestamp example: '2026-01-15T09:30:00.000Z' due_date: type: string description: >- When the task is due, as an ISO 8601 UTC timestamp. null when no due date is set. example: '2026-01-20T17:00:00.000Z' remind_at: type: string description: >- When a reminder for the task fires, as an ISO 8601 UTC timestamp. null when no reminder is set. example: '2026-01-20T09:00:00.000Z' notes: type: string description: Free-form notes on the task. null when none were set. example: Customer prefers a call after 3pm IST chat_id: type: string description: >- Id of the chat the task is linked to (directly, or through its message or ticket). null for todo tasks. example: 120363000000000000@g.us association: $ref: '#/components/schemas/TaskAssociation' completed_metadata: type: object properties: completed_at: type: string description: When the task was closed, as an ISO 8601 timestamp example: '2026-01-21T10:15:00.000Z' completed_by: type: string description: >- Who closed the task: a member's email, or "api" for API changes without an actor example: user@example.com description: >- Completion details, recorded when the task moves to status 'closed' and cleared when it is reopened. null while the task is open or inprogress. description: >- A task in the workspace. Tasks are either standalone to-dos (type: todo) or linked to a chat, message or ticket via association. Tasks belong to the workspace as a whole, not to a specific phone. TaskAssociation: type: object properties: type: type: string enum: - chat - message - ticket description: >- Kind of object the task is linked to: 'chat', 'message' or 'ticket'. Mirrors the task's type. example: message chat_id: type: string description: >- Id of the chat the linked object belongs to — @c.us for 1-1 chats, @g.us for group chats. Present for every association kind; the chat itself for chat tasks, the chat of the message or ticket otherwise. null when the chat could not be resolved. example: 120363000000000000@g.us message_id: type: string description: >- message_id of the linked message. Present only when type is 'message'. example: false_120363000000000000@g.us_AAAAAAAAAAAAAAAAAAAA ticket_id: type: string description: ticket_id of the linked ticket. Present only when type is 'ticket'. example: ACM-042 description: The chat, message or ticket the task is linked to. null for todo tasks. securitySchemes: bearerAuth: type: http scheme: bearer description: >- Your Periskope API token, sent as `Authorization: Bearer `. Generate one from the Periskope dashboard under **Settings → API & Webhooks**. API access requires an active Pro or Enterprise plan. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.