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();curl -X GET 'https://api.periskope.app/v1/tasks/task-aaaaaaaaaaaa' \
-H 'Authorization: Bearer YOUR_API_KEY'{
"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"
}
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "NOT_FOUND_ERROR",
"message": "No task matches task_id",
"status": 404
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Get Task By ID
Looks up a task by its task_id. Responds 404 when no task matches.
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();curl -X GET 'https://api.periskope.app/v1/tasks/task-aaaaaaaaaaaa' \
-H 'Authorization: Bearer YOUR_API_KEY'{
"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"
}
}{
"code": "UNAUTHORIZED_ERROR",
"message": "Invalid bearer auth token",
"status": 401
}{
"code": "NOT_FOUND_ERROR",
"message": "No task matches task_id",
"status": 404
}{
"code": "VALIDATION_ERROR",
"message": "Request validation failed",
"status": 422,
"fields": {
"body.chat_id": {
"message": "chat_id is required"
}
}
}{
"code": "RATE_LIMIT_ERROR",
"message": "You can only make 100 requests per second",
"status": 429
}{
"code": "UNKNOWN_ERROR",
"message": "Internal server error",
"status": 500
}Authorizations
Your Periskope API token, sent as Authorization: Bearer <token>. Generate one from the Periskope dashboard under Settings → API & Webhooks. API access requires an active Pro or Enterprise plan.
Path Parameters
Unique id of the task (task-xxxxxxxxxxxxxxxx), returned when the task was created
1"task-aaaaaaaaaaaa"
Response
The task
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.
Unique id of the task (task-xxxxxxxxxxxxxxxx). Use this value as the task_id path parameter when fetching or updating the task.
"task-aaaaaaaaaaaa"
Title of the task, up to 500 characters
"Call back the customer about the renewal quote"
Kind of task: 'todo' for a standalone task, or 'chat', 'message' or 'ticket' for a task linked to that object. Immutable after creation.
todo, chat, message, ticket "message"
Lifecycle status of the task: 'open', 'inprogress' or 'closed'
open, inprogress, closed "open"
Priority of the task: 1 (low), 2 (medium) or 3 (high)
2
Email of the workspace member the task is assigned to. null when the task is unassigned.
"user@example.com"
Who created the task: a member's email, or "api" when created via the API without a created_by
"api"
Who last changed the task: a member's email, or "api" for API changes without a last_updated_by
"api"
When the task was created, as an ISO 8601 timestamp
"2026-01-15T09:30:00.000Z"
When the task was last updated, as an ISO 8601 timestamp
"2026-01-15T09:30:00.000Z"
When the task is due, as an ISO 8601 UTC timestamp. null when no due date is set.
"2026-01-20T17:00:00.000Z"
When a reminder for the task fires, as an ISO 8601 UTC timestamp. null when no reminder is set.
"2026-01-20T09:00:00.000Z"
Free-form notes on the task. null when none were set.
"Customer prefers a call after 3pm IST"
Id of the chat the task is linked to (directly, or through its message or ticket). null for todo tasks.
"120363000000000000@g.us"
The chat, message or ticket the task is linked to. null for todo tasks.
Show child attributes
Show child attributes
Completion details, recorded when the task moves to status 'closed' and cleared when it is reopened. null while the task is open or inprogress.
Show child attributes
Show child attributes
Was this page helpful?