---
title: "Search tasks"
method: GET
path: "/companies/{company}/tasks"
tags: ["Tasks"]
---

# Search tasks

`GET /companies/{company}/tasks`

## Request

- Base URL: `https://api.factuarea.com/v1`
- URL: `https://api.factuarea.com/v1/companies/{company}/tasks`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Search the tasks of your company across projects, filtering by `q`, `project_id`, `status`, `column_id`, `priority`, `assignee_id` (UUID or `me`), `label_id`, due dates and `completed`.
- `sort` takes `created_at`, `updated_at`, `due_on`, `priority` or `number`; prefix `-` for descending (default `-created_at`).
- Cursor-paginated: pass `next_cursor` as `starting_after`.

## Path parameters

- `company` string, uuid, required

## Query parameters

- `q` string, nullable
- `project_id` string, uuid
- `status` 'planned' | 'active' | 'archived'
- `column_id` string, uuid
- `priority` 'none' | 'low' | 'medium' | 'high' | 'urgent'
- `assignee_id` string
- `label_id` string, uuid
- `due_before` string, date
- `due_after` string, date
- `completed` boolean
- `sort` 'created_at' | '-created_at' | 'updated_at' | '-updated_at' | 'due_on' | '-due_on' | 'priority' | '-priority' | 'number' | '-number'
- `limit` integer
- `starting_after` string, uuid

## Headers

- `Factuarea-Version` string, date

## Response `200`

- object: Page of tasks (`{ data, has_more, next_cursor }`).
  - `data` object[], required: Items on the current page.
    - `id` string, uuid, required: UUID v7 of the task.
    - `object` 'task', required: Stripe-like discriminator. Always `task` for this resource.
    - `key` string, required: Task key: project key and number (`DEV-12`).
    - `number` integer, required: Number of the task in its project.
    - `project_id` string, uuid, required: UUID of the project.
    - `column_id` string, uuid, nullable, required: UUID of the board column, or `null` in the backlog (`planned`) or when `archived`.
    - `status` 'planned' | 'active' | 'archived', required: Board status: `planned` (backlog), `active` (in a column of the board) or `archived`.
    - `priority` 'none' | 'low' | 'medium' | 'high' | 'urgent', required: Task priority.
    - `title` string, required: Task title.
    - `description` string, nullable, required: Description in Markdown, or `null`.
    - `start_on` string, date, nullable, required: Start date, or `null`.
    - `due_on` string, date, nullable, required: Due date, or `null`.
    - `assignee_id` string, uuid, nullable, required: UUID of the assigned member, or `null`.
    - `labels` object[], required: Labels of the task.
      - `id` string, uuid, required: UUID of the label.
      - `name` string, required
      - `color` string, required
    - `custom_fields` object[], required: Values of the custom fields of the project.
      - `field_id` string, uuid, required: UUID of the custom field.
      - `name` string, required
      - `type` 'text' | 'number' | 'date' | 'dropdown' | 'boolean' | 'multiselect', required
      - `value` string, nullable, required: Value serialized as a string (a JSON array for `multiselect`), or `null`.
    - `completed_at` string, date-time, nullable, required: When the task was completed, or `null` while open.
    - `created_at` string, date-time, required: Creation timestamp.
    - `updated_at` string, date-time, required: Last update timestamp.
    - `counts` object, required: Counters of the task.
      - `subtasks_total` integer, required
      - `subtasks_completed` integer, required
      - `comments` integer, required
      - `attachments` integer, required
  - `has_more` boolean, required: `true` when there are more objects after this page.
  - `next_cursor` string, nullable, required: Value to pass as `starting_after` to get the next page (the `id` of the last object), or `null` when `has_more` is `false`.

## Other responses

- `400`: The request is syntactically malformed — e.g. an unknown query parameter, an integer parameter with non-numeric value, or a value outside the documented range. `parameter_unknown` with `subcode` `retired_active_profile_header`: the retired `X-Active-Profile` header was sent; the company goes in the path. `parameter_invalid_format` on `Factuarea-Version`: the header is not a `YYYY-MM-DD` date. `unsupported_api_version`: the `Factuarea-Version` date is not a supported version.
- `401`: Missing or invalid API key.
- `403`: The request is authenticated but not allowed: the API key lacks the required scope (`insufficient_scope`), the plan does not include the public API or this feature (`addon_not_active`, `feature_not_available_in_plan`), or the module is not available with a test key (`module_not_available_in_sandbox`).
- `404`: The requested resource does not exist or belongs to another company. `profile_not_found`: the company in the path does not exist, is not in the API key scope or belongs to the other environment (live or test).
- `422`: Validation failed. The `error.param` field identifies which input is invalid.
- `429`: Rate limit exceeded. Retry after the duration in `Retry-After`.
- `500`: Unexpected server error.

---

[API](https://skmtc.dev/factuarea/apis/factuarea-public-api.md) · [All operations](https://skmtc.dev/factuarea/apis/factuarea-public-api/llms.txt) · [OpenAPI document](https://skmtc.dev/factuarea/apis/factuarea-public-api/revisions/718e77934422?raw)