---
title: "List tasks"
method: GET
path: "/tasks"
tags: ["Tasks"]
---

# List tasks

`GET /tasks`

## Request

- Base URL: `https://api.parley.so/v1`
- URL: `https://api.parley.so/v1/tasks`
- Auth: HTTP bearer

List the tasks the caller can see, newest first by default. A task on a project is visible to the people who can see that project; any other task is visible to everyone in the organization. Filter by status, assignee, due date, the record a task is about, title, and when tasks were created or updated. Each task includes the caller's own reminder for it.

## Query parameters

- `search` string: Case-insensitive. Every word must match the title or a text custom field.
- `statuses` string[]: Only tasks whose status is one of these.
- `assigneeId` string: Only tasks assigned to the user with this ID.
- `dueSince` string, date: Only tasks due on or after this day, as YYYY-MM-DD.
- `dueBefore` string, date: Only tasks due before this day, as YYYY-MM-DD.
- `projectId` string: Only tasks about this project.
- `accountId` string: Only tasks about this account.
- `contactId` string: Only tasks about this contact.
- `createdSince` string: Only records created at or after this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `createdBefore` string: Only records created before this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `updatedSince` string: Only records last updated at or after this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `updatedBefore` string: Only records last updated before this time. An ISO 8601 date (YYYY-MM-DD, read as UTC midnight) or date-time.
- `sort` 'title' | '-title' | 'createdAt' | '-createdAt' | 'updatedAt' | '-updatedAt': Sort order: a field name, prefixed with - for descending. Defaults to -createdAt.
- `cursor` string: Opaque cursor from nextCursor. Pass the same filters and sort. Omit for the first page.
- `limit` integer: Maximum number of items to return.

## Response `200`

OK

- object
  - `data` Task[], required
    - `id` string, required: The task ID.
    - `title` string, required: Task title.
    - `status` 'todo' | 'in_progress' | 'done' | 'cancelled', nullable, required: Where the task stands: todo, in_progress, done, or cancelled. done and cancelled close it.
    - `assignee` UserRef, required: A reference to a person in the organization.
      - `id` string, required: The user's ID.
      - `name` string, nullable, required: The user's full name, or null when it is unknown, as for someone who has left the organization.
      - `email` string, nullable, required: The user's email address, or null when it is unknown.
    - `dueDate` string, date, nullable, required: The day the task is due, as YYYY-MM-DD.
    - `description` string, nullable, required: Details, or null.
    - `linkedRecord` RecordRef, required: A reference to a project, account, or contact.
      - `type` 'project' | 'account' | 'contact', required: The kind of record: project, account, or contact.
      - `id` string, required: Its ID.
      - `name` string, required: The record's name. A contact's is its first and last name, or an email address when it has no name.
    - `reminder` object, nullable, required: Your reminder for the task, or null. Reminders are personal: each person sees only their own.
      - `remindAt` string, date-time, required: When Parley reminds you, through your notification settings.
      - `sentAt` string, date-time, nullable, required: When the reminder was sent, or null until then.
    - `createdAt` string, date-time, required: When the task was created.
    - `updatedAt` string, date-time, required: When the task was last renamed or linked to a different record. Changes to its status, assignee, due date, description, field values, and reminders do not change it.
    - `fields` object, required: Custom field values, keyed by field name, with a key for every field defined for tasks (null when unset). The value's shape follows the field's type. Status, assignee, due date, and description are properties of the task, not fields.
  - `nextCursor` string, nullable, required: Cursor for the next page, or null on the last page.

## Other responses

- `400`: The request was invalid. VALIDATION_FAILED, INVALID_CURSOR.
- `401`: Missing or invalid credentials. UNAUTHORIZED.
- `403`: You don't have permission. FORBIDDEN.
- `429`: Too many requests, or a usage limit was reached. TOO_MANY_REQUESTS.

---

[API](https://skmtc.dev/parley/apis/parley-api.md) - [All operations](https://skmtc.dev/parley/apis/parley-api/llms.txt) - [OpenAPI document](https://skmtc.dev/parley/apis/parley-api/revisions/6b78aeee07bc?raw)