---
title: "Search tasks"
method: POST
path: "/api/tasks/search"
tags: ["Tasks"]
---

# Search tasks

`POST /api/tasks/search`

## Request

- Base URL: `https://core-api.getaptly.com`
- URL: `https://core-api.getaptly.com/api/tasks/search`
- Auth: one of:
  - API key in header `x-token`
  - API key in header `Authorization`
- TypeScript: <https://skmtc.dev/getaptly/apis/aptly-api/docs/api/tasks/search/post.ts> (a function with typed inputs; its response is checked against the schema)

Query tasks for the authenticated company. All body fields are optional filters.
Date-range filters (`dueAt`, `checkedAt`, `updatedAt`) take an object of
`{ startDate, endDate }` — either bound may be supplied independently. Set
`useCount: true` to return `{ count }` instead of `{ tasks }`.

## Request body

- object
  - `userIds` string[]: Restrict to tasks assigned to these user ids.
  - `isChecked` boolean: Filter by completion state.
  - `isPinned` boolean
  - `archived` boolean
  - `taskPriority` string: One of asap|high|medium|low. The search filter is named `taskPriority`; the field is `priority` on the task itself and in update bodies.
  - `status` union: One status or a list of statuses (backlog|notStarted|inProgress|onHold|completed).
    - string
    - string[]
  - `streamId` string
  - `channelId` string
  - `aptletUuid` string: Board UUID.
  - `aptletInstanceId` string
  - `leaderboard` boolean
  - `onlyAssigned` boolean
  - `unAssigned` boolean
  - `useCount` boolean: Return a count instead of the task list.
  - `limit` integer
  - `dueAt` TaskDateRange: Date-range filter. Either bound may be supplied independently — `startDate` maps to `$gte`, `endDate` to `$lte`.
    - `startDate` string, date-time
    - `endDate` string, date-time
  - `checkedAt` TaskDateRange: Date-range filter. Either bound may be supplied independently — `startDate` maps to `$gte`, `endDate` to `$lte`.
    - `startDate` string, date-time
    - `endDate` string, date-time
  - `updatedAt` TaskDateRange: Date-range filter. Either bound may be supplied independently — `startDate` maps to `$gte`, `endDate` to `$lte`.
    - `startDate` string, date-time
    - `endDate` string, date-time

## Response `200`

Matching tasks (or a count).

- object
  - `tasks` Task[]
    - `_id` string
    - `companyId` string
    - `title` string
    - `mergedTitle` string: Title with `{{ }}` merge tags resolved against the task's representative contact, the company, and the acting user.
    - `description` string
    - `mergedDescription` string: Description with `{{ }}` merge tags resolved (HTML output).
    - `userId` string: Assigned user id.
    - `checked` boolean
    - `archived` boolean
    - `status` string
    - `priority` string
    - `dueAt` string, date-time
    - `aptletInstanceId` string
    - `aptletUuid` string
    - `attachments` object[]
      - `_id` string
      - `name` string
      - `type` string
    - `priorityLabel` string: Present only when includeMetadata=true.
    - `statusLabel` string: Present only when includeMetadata=true.
    - `assignee` object: Present only when includeMetadata=true.
      - `_id` string
      - `fullName` string
  - `count` integer: Present instead of `tasks` when `useCount` is true.

## Other responses

- `400`: Invalid filter value.
- `401`: Invalid or missing credential.

---

[API](https://skmtc.dev/getaptly/apis/aptly-api.md) - [All operations](https://skmtc.dev/getaptly/apis/aptly-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getaptly/apis/aptly-api/revisions/75c367e0b8e5?raw)