# Filter tasks

```http
POST https://secure.yoprint.com/v1/api/store/{team_slug}/work_pipeline/filter
```

- API version: v1
- Operation ID: `v1_public_work_pipeline_filter`
- Section: Production › [Tasks](https://developer.yoprint.com/reference/tasks.md)
- Web page: https://developer.yoprint.com/reference/tasks/v1-work-pipeline-filter/
- Authentication: `Authorization: Bearer YOUR_API_KEY`

Returns one page of your team's tasks across all jobs that match the filters, in the order you ask for.

Only tasks of live jobs on sales orders are listed.

Every condition in `filters` must match (they are joined with AND). Omit `filters` for no filter; an empty array is a 422. A `key` that isn't in the table, a missing `operator` or `value`, or a value of the wrong kind fails the whole request with 422; the message for `filters` (or `sort`) is the bare rule name `validation.filter_rule` (or `validation.filter_sort_rule`), with no detail, so check each filter against the table. Send real values: no key here matches empty columns with `"null"` or `""` (for dates, use the `..._is_set` keys where the table has them). Hash ids in `value` are decoded for you. `system-current-user` stands for the caller only where a key's row says so; elsewhere it is compared as a raw value, so with `in` it matches nothing and with `nin` it matches every row that has a value.

| `key` | Kind | Operators and `value` | Meaning |
| --- | --- | --- | --- |
| `status_id` | Hash ids | `in` or `nin`, with an array of hash ids. | The task status (statuses belong to a task preset). |
| `status_type` | Options | `in` or `nin`, with an array of the listed values. | The kind of status: `start` (Pending), `pre_production` or `in_progress` (In Progress), `end` (Completed). |
| `pipeline_id` | Hash ids | `in` or `nin`, with an array of hash ids. | The task preset. |
| `assigned_users` | Hash ids | `in` or `nin`, with an array of hash ids. | Assigned users (user hash ids, or `system-current-user`). `in` matches tasks with one of them. `nin` matches tasks that have an assignee outside the list, not tasks without those users. |
| `assigned_to_me` | Yes or no | `eq` or `neq`, with `true` or `false`. | Send `eq` `true` for tasks assigned to the caller. The operator isn't read (`neq true` means the same). `false` matches tasks that have someone other than the caller assigned; unassigned tasks never match. |
| `order_created_by` | Hash ids | `in` or `nin`, with an array of hash ids. | Who created the sales order (user hash ids). `system-current-user` is not supported here: with `in` it matches nothing, with `nin` everything. |
| `is_rush` | Yes or no | `eq` or `neq`, with `true` or `false`. | The task belongs to a rush job. |
| `start_date` | Date | `eq`, `gte` or `lte`, with a whole number of days counted from now (UTC). See below. | The task's start date. |
| `due_date` | Date | `eq`, `gte` or `lte`, with a whole number of days counted from now (UTC). See below. | The task's due date. |
| `start_date_is_set` | Yes or no | `eq` or `neq`, with `true` or `false`. | The task has a start date (`eq true`) or none (`eq false`). Use `eq` only: any `neq` means "has the date". |
| `due_date_is_set` | Yes or no | `eq` or `neq`, with `true` or `false`. | The task has a due date (`eq true`) or none (`eq false`). Use `eq` only: any `neq` means "has the date". |
| `status_last_change_date` | Date | `eq`, `gte` or `lte`, with a whole number of days counted from now (UTC). See below. | When the status last changed. |
| `status_completion_date` | Date | `eq`, `gte` or `lte`, with a whole number of days counted from now (UTC). See below. | When the task reached a Completed status. |
| `search` | Text search | Any operator (`ct` reads best). The value must not be empty. | Task name, plus the job and order fields Filter jobs searches. |

A date filter's `value` is a whole number of days, counted from the moment of the request in UTC: `eq` N matches the whole UTC day N days from today (0 is today, -1 yesterday); `gte` N matches dates on or after now plus N days; `lte` N matches dates on or before now **minus** N days. So "due in the next 7 days" is `due_date gte 0` and `due_date lte -7`, and "overdue" is `due_date lte 0`. This differs from the v2 filters (Filter invoices, the production control calendar), where `lte` and `gte` both count forward.

The response is one page with `pagination`. The page size is the team's list page size setting (50 unless the team changed it); `per_page` is not read. Send `page` (from 1) in the body or the query string for later pages.

## Permission

Any member of the team. No sales order permission is checked.

## Path parameters

- `team_slug` (string, required): Your team slug, shown as Team ID next to your API key in Profile. Example `your-team`.

## Request body

Content type `application/json`, optional.

Fields:

- `filters` (array of objects, optional): Conditions, all of which must match. Omit for no filter. At least 1 item.
  - Each item:
    - `key` (string, required): What to filter on. See the table in the description. One of: `"status_id"`, `"status_type"`, `"pipeline_id"`, `"assigned_users"`, `"assigned_to_me"`, `"order_created_by"`, `"is_rush"`, `"start_date"`, `"due_date"`, `"start_date_is_set"`, `"due_date_is_set"`, `"status_last_change_date"`, `"status_completion_date"`, `"search"`.
    - `operator` (string, required): How to compare. Each kind of key accepts only some operators. One of: `"eq"`, `"neq"`, `"gt"`, `"gte"`, `"lt"`, `"lte"`, `"in"`, `"nin"`, `"bt"`, `"ct"`, `"sw"`, `"ew"`.
    - `value` (string | number | boolean | array, required): What to compare with: text, a number of days, true or false, or an array of hash ids or options, by kind of key.
- `page` (integer, optional): The page to read. Default `1`. Minimum 1.
- `sort` (array of objects, optional): Sort keys, applied in order. Without `sort` the order is not guaranteed.
  - Each item:
    - `direction` (string, required): One of: `"asc"`, `"desc"`.
    - `key` (string, required): One of: `"status_id"`, `"status_label"`, `"pipeline_id"`, `"job_id"`, `"start_date"`, `"due_date"`, `"status_last_change_date"`, `"status_completion_date"`, `"job_item_count"`, `"order_cust_due_date"`, `"order_due_date"`, `"order_ship_due_date"`, `"order_ship_due_date_undated_last"`, `"created_at_id"`.

### Example request

```bash
curl -X POST 'https://secure.yoprint.com/v1/api/store/your-team/work_pipeline/filter' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'X-Yoprint-Decimal-Format: exact-v1' \
  -H 'Content-Type: application/json' \
  -d '{
    "filters": [
      {
        "key": "assigned_to_me",
        "operator": "eq",
        "value": true
      },
      {
        "key": "status_type",
        "operator": "nin",
        "value": [
          "end"
        ]
      }
    ],
    "page": 1,
    "sort": [
      {
        "direction": "asc",
        "key": "due_date"
      }
    ]
  }'
```

## Response

`200` Successful response.

Fields:

- `data` (array of objects, required)
  - Each item:
    - `assigned_users` (array of objects, optional): Who is assigned.
      - Each item:
        - `avatar_url` (string | null, optional)
        - `id` (string, optional): The user.
        - `name` (string, optional)
    - `created_at` (string (date-time), optional)
    - `due_date` (string (date-time) | null, optional): Task due date. ISO 8601 with offset, or null.
    - `id` (string, optional): The task.
    - `job_id` (string, optional): The job.
    - `job_is_rush` (boolean | integer | null, optional)
    - `job_item_count` (number | null, optional)
    - `job_name` (string | null, optional)
    - `job_scoped_id` (string, optional): The job number with its prefix.
    - `job_status_id` (string | null, optional): The job's current status.
    - `name` (string, optional)
    - `note` (string | null, optional)
    - `order_id` (string, optional): The order.
    - `order_name` (string | null, optional)
    - `order_scoped_id` (string | null, optional): The order number.
    - `pipeline_id` (string, optional): The task preset it comes from.
    - `position` (integer, optional): Order among tasks; lower comes first. 0 when unset.
    - `sales_order` (object, optional): A summary of the job's order.
      - `created_by` (string | null, optional): Who created the order.
      - `cust_due_date` (string (date-time) | null, optional): Order customer due (in-hand) date. ISO 8601 with offset, or null.
      - `customer_id` (string | null, optional): The customer.
      - `customer_name` (string | null, optional)
      - `due_date` (string (date-time) | null, optional): Order production due date. ISO 8601 with offset, or null.
      - `external_type` (string | null, optional): `shopify` when the order came from Shopify, else null.
      - `is_quote` (boolean, optional)
      - `issue_date` (string (date-time) | null, optional): Order issue date. ISO 8601 with offset, or null.
      - `object_type` (string | null, optional): `sales_order` or `quote`.
      - `ship_due_date` (string (date-time) | null, optional): Order ship-by date. ISO 8601 with offset, or null.
      - `shopify_deleted_externally` (boolean, optional)
      - `shopify_deleted_externally_at` (string (date-time) | null, optional): When it was deleted in Shopify. ISO 8601 with offset, or null.
      - `start_date` (string (date-time) | null, optional): Order production start. ISO 8601 with offset, or null.
      - `status_id` (string | null, optional): The order status.
    - `start_date` (string (date-time) | null, optional): Task start. ISO 8601 with offset, or null.
    - `status` (object, optional): A status: label, kind and place in the list.
      - `color` (string | null, optional): Hex color.
      - `customer_label` (string, optional)
      - `id` (string, optional): The status.
      - `label` (string, optional)
      - `pipeline_id` (string, optional): Only on the statuses of a task preset (`role` `pipeline`): the task preset. Absent on other statuses.
      - `position` (integer, optional): Its place in the team's list: sort by it to find the next status.
      - `role` (string, optional): Which list it belongs to: `job` for job statuses, `pipeline` for the statuses of a task preset. One of: `"order"`, `"quote"`, `"job"`, `"purchase_order"`, `"shipment"`, `"customer_message"`, `"pipeline"`.
      - `trashed` (boolean, optional): The status was deleted.
      - `type` (string, optional): The kind of status: `start` (Pending), `pre_production` and `in_progress` (In Progress), `end` (Completed). One of: `"start"`, `"pre_production"`, `"in_progress"`, `"end"`.
    - `status_completion_date` (string (date-time) | null, optional): When it reached a Completed status. ISO 8601 with offset, or null.
    - `status_id` (string, optional): The task's status (a status of its task preset).
    - `status_last_change_date` (string (date-time) | null, optional): When the status last changed. ISO 8601 with offset, or null.
    - `updated_at` (string (date-time), optional)
- `status` (integer, required)
- `success` (boolean, required)
- `pagination` (object, optional)
  - `count` (integer, required)
  - `currentPage` (integer, required)
  - `links` (object | array of any, required): Links to the neighbouring pages: `previous` and `next`, each present only when that page exists. An empty list, `[]`, when there is only one page.
    - `next` (string (uri), optional): The next page.
    - `previous` (string (uri), optional): The previous page.
  - `perPage` (integer, required)
  - `total` (integer, required)
  - `totalPages` (integer, required)

Example response:

```json
{
  "data": [
    {
      "assigned_users": [
        {
          "avatar_url": null,
          "id": "4mdDkMg3dgQOa3",
          "name": "Alex Rivera"
        }
      ],
      "created_at": "2026-11-03T15:00:00+00:00",
      "due_date": "2026-11-05T17:00:00+00:00",
      "id": "hpioY1gDBQZdbI",
      "job_id": "WaGvtaWsx7Kcn4",
      "job_is_rush": 1,
      "job_item_count": 48,
      "job_name": "Front print",
      "job_scoped_id": "JOB-2419",
      "job_status_id": "scaWHQnPLtqMPT",
      "name": "Burn screens",
      "note": null,
      "order_id": "sFbALVSYD55eXe",
      "order_name": "Team shirts",
      "order_scoped_id": "SO1001",
      "pipeline_id": "SE3SfXjt6dPfnH",
      "position": 1,
      "sales_order": {
        "customer_id": "ifAHmADekGZ6id",
        "customer_name": "Northwind Apparel",
        "is_quote": false,
        "object_type": "sales_order",
        "status_id": "wgbOT87gGZvhgy"
      },
      "start_date": "2026-11-04T09:00:00+00:00",
      "status": {
        "color": "#2196f3",
        "customer_label": "In Progress",
        "id": "hTFITko5Q0R83y",
        "label": "Burning",
        "pipeline_id": "SE3SfXjt6dPfnH",
        "position": 2,
        "role": "pipeline",
        "trashed": false,
        "type": "in_progress"
      },
      "status_completion_date": null,
      "status_id": "hTFITko5Q0R83y",
      "status_last_change_date": "2026-11-03T15:05:00+00:00",
      "updated_at": "2026-11-03T15:05:00+00:00"
    }
  ],
  "pagination": {
    "count": 1,
    "currentPage": 1,
    "links": [],
    "perPage": 50,
    "total": 1,
    "totalPages": 1
  },
  "status": 200,
  "success": true
}
```

## Errors

- `401` The API key is missing or wrong (`unauthenticated`).
- `403` You are not allowed to do this. `api_access_not_in_plan`: your team's plan doesn't include API access (Pro and above, with an active subscription or trial), so every request answers this until the team upgrades. When your role lacks the permission the operation needs, the body is only `{"message": "Insufficient Permission"}`. Other refusals use the error envelope, with `unauthorized` or `user_is_not_authorized`.
- `404` Not found. `page_not_found`: the team slug is unknown, you are not a member of the team, or an id in the path is not one of this team's. `code: null`, with a message that starts "No query results for": there is no record with that id.
- `422` The request was refused and changed nothing. `validation_failed` lists what to fix in `error.fields`; other codes name a business rule, explained in `error.message`. A few checks answer with only `{"message": "..."}`. An operation that calls another service (a payment provider, a carrier, an accounting app) can answer `connect_timeout` ("Please retry again") when that service does not answer in time: the change may or may not have happened there, so read the record back before you retry.
  - When: A filter has an unknown `key`, a missing part, or an operator or value its kind doesn't accept; or `filters` is an empty array. Fix: Check each filter against the table.

## Notes

- `assigned_users` with `nin` keeps its old meaning on this route: "has someone assigned who isn't in the list".

## Related

- [List tasks in a date range](https://developer.yoprint.com/reference/tasks/v1-work-pipeline-calendar.md): `POST /v1/api/store/{team_slug}/work_pipeline/calendar`
- [List the tasks of a job](https://developer.yoprint.com/reference/tasks/v2-job-work-pipeline-index-for-job.md): `GET /v2/api/store/{team_slug}/v2/job/{hash_id}/work_pipeline`
- [List the task statuses of a task preset](https://developer.yoprint.com/reference/statuses/v1-status-list-pipeline.md): `GET /v1/api/store/{team_slug}/setting/status/pipeline/{hash_id}`