> ## 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 All Tasks

> Returns the tasks of the workspace, newest first, across every task kind.



## OpenAPI

````yaml api-reference/openapi-generated.json GET /v1/tasks
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:
    get:
      tags:
        - Tasks
      summary: List tasks
      description: >-
        Returns the tasks of the workspace, newest first, across every task
        kind.
      operationId: listTasks
      parameters:
        - schema:
            type: integer
            nullable: true
            minimum: 0
            description: >-
              Number of records to skip before the first returned record. Use
              together with limit to paginate: page N is offset = N * limit.
              Defaults to 0.
            example: 0
          required: false
          description: >-
            Number of records to skip before the first returned record. Use
            together with limit to paginate: page N is offset = N * limit.
            Defaults to 0.
          name: offset
          in: query
        - schema:
            type: integer
            minimum: 1
            maximum: 2000
            description: >-
              Maximum number of records to return in one page, up to 2000.
              Defaults to 1000.
            example: 1000
          required: false
          description: >-
            Maximum number of records to return in one page, up to 2000.
            Defaults to 1000.
          name: limit
          in: query
        - schema:
            type: string
            description: >-
              One or more task kinds, comma-separated: 'todo', 'chat',
              'message', 'ticket'.
            example: todo,chat
          required: false
          description: >-
            One or more task kinds, comma-separated: 'todo', 'chat', 'message',
            'ticket'.
          name: type
          in: query
        - schema:
            type: string
            description: >-
              One or more statuses, comma-separated: 'open', 'inprogress',
              'closed'.
            example: open,inprogress
          required: false
          description: >-
            One or more statuses, comma-separated: 'open', 'inprogress',
            'closed'.
          name: status
          in: query
        - schema:
            type: string
            description: >-
              One or more priorities, comma-separated: 1 (low), 2 (medium), 3
              (high).
            example: 2,3
          required: false
          description: >-
            One or more priorities, comma-separated: 1 (low), 2 (medium), 3
            (high).
          name: priority
          in: query
        - schema:
            type: string
            description: One or more assignee member emails, comma-separated.
            example: user@example.com
          required: false
          description: One or more assignee member emails, comma-separated.
          name: assignee
          in: query
        - schema:
            type: string
            description: One or more creator member emails (or "api"), comma-separated.
            example: user@example.com
          required: false
          description: One or more creator member emails (or "api"), comma-separated.
          name: created_by
          in: query
        - schema:
            type: string
            description: Only tasks created at or after this time (ISO 8601).
            example: '2026-01-01T00:00:00Z'
          required: false
          description: Only tasks created at or after this time (ISO 8601).
          name: start_time
          in: query
        - schema:
            type: string
            description: Only tasks created at or before this time (ISO 8601).
            example: '2026-01-31T23:59:00Z'
          required: false
          description: Only tasks created at or before this time (ISO 8601).
          name: end_time
          in: query
        - schema:
            type: string
            description: Only tasks due at or after this time (ISO 8601).
            example: '2026-01-01T00:00:00Z'
          required: false
          description: Only tasks due at or after this time (ISO 8601).
          name: due_date_start
          in: query
        - schema:
            type: string
            description: Only tasks due at or before this time (ISO 8601).
            example: '2026-01-31T23:59:00Z'
          required: false
          description: Only tasks due at or before this time (ISO 8601).
          name: due_date_end
          in: query
        - schema:
            type: string
            enum:
              - created_at
              - due_date
            description: 'Field to sort by: ''created_at'' (default) or ''due_date''.'
            example: due_date
          required: false
          description: 'Field to sort by: ''created_at'' (default) or ''due_date''.'
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: 'Sort direction: ''asc'' or ''desc'' (default).'
            example: desc
          required: false
          description: 'Sort direction: ''asc'' or ''desc'' (default).'
          name: sort_order
          in: query
        - schema:
            type: string
            description: Case-insensitive substring search on the task title.
            example: hello
          required: false
          description: Case-insensitive substring search on the task title.
          name: q
          in: query
      responses:
        '200':
          description: Paginated list of tasks
          content:
            application/json:
              schema:
                type: object
                properties:
                  from:
                    type: integer
                    description: >-
                      1-based index of the first record in this page (offset +
                      1).
                    example: 1
                  to:
                    type: integer
                    description: 1-based index of the last record in this page.
                    example: 20
                  count:
                    type: integer
                    description: >-
                      Number of records in this page — the length of the `tasks`
                      array, not the total across all pages.
                    example: 20
                  tasks:
                    type: array
                    items:
                      $ref: '#/components/schemas/Task'
                    description: The tasks in this page.
              examples:
                default:
                  summary: Response body
                  value:
                    from: 1
                    to: 20
                    count: 20
                    tasks:
                      - 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
        '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.listTasks();
              console.log(response);
            }

            main();
        - lang: bash
          label: cURL
          source: |-
            curl -X GET 'https://api.periskope.app/v1/tasks' \
              -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 —
            <countrycode><number>@c.us for 1-1 chats, <group-id>@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 <token>`.
        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.