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

# Search tasks

`POST /tasks/search`

## Request

- Base URL: `https://api.copper.com/developer_api/v1`
- URL: `https://api.copper.com/developer_api/v1/tasks/search`
- Auth: HTTP bearer

Search tasks. Response uses a pagination envelope (`page_number`,`total`,`data`) so ChatGPT can read pagination info; the X-PW-TOTAL header still exists. Paginate with page_number/page_size (max 200) until received records equal total. Limited to 100K results.

## Query parameters

- `custom_field_computed_values` boolean

## Request body

- object
  - `name` union: Filter by task name. Use simple string for exact match (case-insensitive), or use object format with special_value for partial matching capability.
    - string: Simple string for exact match (case-insensitive). Example: 'Follow up call' will only match tasks named exactly 'Follow up call'.
    - object: Advanced object format for controlling match type
      - `value` string, required: The task name to search for
      - `special_value` object[], required: Array specifying the match type
        - `type` 'partial' | 'exact', required: Match type: 'partial' for substring matching (e.g., 'Follow' matches 'Follow up call'), 'exact' for exact match
  - `phrase` union: Filter by task name (alias for 'name'). Use simple string for exact match (case-insensitive), or use object format with special_value for partial matching capability.
    - string: Simple string for exact match (case-insensitive). Alias for 'name' parameter.
    - object: Advanced object format for controlling match type
      - `value` string, required: The task name/phrase to search for
      - `special_value` object[], required: Array specifying the match type
        - `type` 'partial' | 'exact', required: Match type: 'partial' for substring matching, 'exact' for exact match
  - `related_resource` object: Filter by the primary related resource for the task
    - `id` integer: The ID of the related resource
    - `type` 'person' | 'company' | 'opportunity' | 'project' | 'lead': The type of the related resource
  - `tags` string[]: An array of tags to filter by
  - `assignee_ids` integer[]: An array of assignee IDs to filter by (the user IDs who own these tasks)
  - `statuses` string[]: An array of statuses to filter by
  - `priorities` string[]: An array of priorities to filter by
  - `minimum_due_date` integer: Unix timestamp for the minimum due date
  - `maximum_due_date` integer: Unix timestamp for the maximum due date
  - `minimum_reminder_date` integer: Unix timestamp for the minimum reminder date
  - `maximum_reminder_date` integer: Unix timestamp for the maximum reminder date
  - `minimum_completed_date` integer: Unix timestamp for the minimum completed date
  - `maximum_completed_date` integer: Unix timestamp for the maximum completed date
  - `minimum_close_date` integer: Unix timestamp for the minimum creation date
  - `maximum_close_date` integer: Unix timestamp for the maximum creation date
  - `minimum_modified_date` integer: Unix timestamp for the minimum modification date
  - `maximum_modified_date` integer: Unix timestamp for the maximum modification date
  - `custom_fields` object[]: An array of custom field filters. Each filter can include custom_field_definition_id and optionally allow_empty to include records where the field is empty
    - `custom_field_definition_id` integer: The custom field definition ID to filter by
    - `value` unknown
    - `allow_empty` boolean: When true, includes records where this custom field is empty/null
  - `sort_by` 'name' | 'assigned_to' | 'related_to' | 'status' | 'priority' | 'due_date' | 'reminder_date' | 'completed_date' | 'date_created' | 'date_modified': The field on which to sort the results
  - `sort_direction` 'asc' | 'desc': The direction in which to sort the results
  - `page_number` integer: The page number (starting with 1) that you would like to view
  - `page_size` integer: The number of entries included in a page of results

## Response `200`

Tasks retrieved successfully

- object: Standard paginated response envelope returned for ChatGPT-only requests. Mirrors the previous pagination headers by surfacing totals inside the response body while keeping the original headers available.
  - `page_number` integer, required: Current page number (defaults to 1 when not provided in the request).
  - `total` integer, required: Total number of records that match the request filters (equivalent to the X-PW-TOTAL header).
  - `data` Task[], required: Records returned for the requested page. The item schema depends on the endpoint using this envelope.
    - `id` integer, required: Unique identifier for the task
    - `name` string, required: The name of the task
    - `related_resource` object, nullable: The primary related resource for the task
      - `id` integer: The ID of the related resource
      - `type` string: The type of the related resource
    - `assignee_id` integer, nullable: Unique identifier of the user that will be the owner of the task
    - `due_date` integer, nullable: The date on which the task is due (Unix timestamp)
    - `reminder_date` integer, nullable: The date on which to receive a reminder about the task (Unix timestamp)
    - `completed_date` integer, nullable: The date on which the task was completed (Unix timestamp). This is automatically set when the status changes from Open to Completed, and cannot be set directly.
    - `priority` 'None' | 'Low' | 'Medium' | 'High': The priority of the task
    - `status` 'Open' | 'Completed': The status of the task
    - `details` string, nullable: Description of the task
    - `tags` string[]: An array of the tags associated with the task
    - `custom_fields` object[]: An array of custom field values belonging to the task. When custom_field_computed_values query parameter is true, each field will include a computed_value with human-readable labels for Dropdown and Multi-select fields.
      - `custom_field_definition_id` integer: The id of the custom field definition for which this custom field stores a value
      - `value` unknown
      - `computed_value` unknown
    - `custom_activity_type_id` integer, nullable: The custom activity type ID associated with this task
    - `date_created` integer: A Unix timestamp representing the time at which this task was created
    - `date_modified` integer: A Unix timestamp representing the time at which this task was last modified

## Other responses

- `400`: Bad Request - The request was invalid or cannot be served
- `401`: Unauthorized - Authentication credentials were missing or incorrect
- `429`: Too Many Requests - Rate limit exceeded
- `500`: Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.dev/copper/apis/copper-crm-read-only-api.md) - [All operations](https://skmtc.dev/copper/apis/copper-crm-read-only-api/llms.txt) - [OpenAPI document](https://skmtc.dev/copper/apis/copper-crm-read-only-api/revisions/96adc8557a40?raw)