# Search tasks by criteria

`GET /api/search/task`

URL: https://repsona.com/api/get-search-task

Returns matching tasks within joined projects. result=ids returns all matching task ids; result=items returns paged display summaries. Multiple values in one field are OR-ed. Each field mode assigns the condition to a group: and (must match), or (cross-field any-match group), exclude (must not match; tasks with the field unset are kept unless "none" is listed). The literal value "none" means the field is unset.

## Parameters

| name | in | type | required | description |
| --- | --- | --- | --- | --- |
| `projectId` | query | "@all" \| integer | required | A project ID, or `@all` for every open project you belong to. |
| `q` | query | string |  | Keywords to search for in the task name and description (up to 200 characters). Separate keywords with spaces (up to 5); a task must match all of them. |
| `statusIds` | query | string |  | Comma-separated status IDs (up to 100). `none` matches tasks with no value. |
| `statusMode` | query | and \| or \| exclude |  | How to combine `statusIds`. `and`: tasks matching any listed value, required together with the other conditions; `or`: tasks matching any listed value, where a match on any `or` condition is enough; `exclude`: tasks matching none of the values. Defaults to `and`. |
| `milestoneIds` | query | string |  | Comma-separated milestone IDs (up to 100). `none` matches tasks with no value. |
| `milestoneMode` | query | and \| or \| exclude |  | How to combine `milestoneIds`. `and`: tasks matching any listed value, required together with the other conditions; `or`: tasks matching any listed value, where a match on any `or` condition is enough; `exclude`: tasks matching none of the values. Defaults to `and`. |
| `priorities` | query | string |  | Comma-separated priorities (up to 100): `1` high, `2` medium, `3` low. `none` matches tasks with no priority. |
| `priorityMode` | query | and \| or \| exclude |  | How to combine `priorities`. `and`: tasks matching any listed value, required together with the other conditions; `or`: tasks matching any listed value, where a match on any `or` condition is enough; `exclude`: tasks matching none of the values. Defaults to `and`. |
| `responsibleUserIds` | query | string |  | Comma-separated user IDs of the assignee (up to 100). `none` matches tasks with no value. |
| `responsibleUserMode` | query | and \| or \| exclude |  | How to combine `responsibleUserIds`. `and`: tasks matching any listed value, required together with the other conditions; `or`: tasks matching any listed value, where a match on any `or` condition is enough; `exclude`: tasks matching none of the values. Defaults to `and`. |
| `ballHoldingUserIds` | query | string |  | Comma-separated user IDs of the ball holder (the person who has to act next) (up to 100). `none` matches tasks with no value. |
| `ballHoldingUserMode` | query | and \| or \| exclude |  | How to combine `ballHoldingUserIds`. `and`: tasks matching any listed value, required together with the other conditions; `or`: tasks matching any listed value, where a match on any `or` condition is enough; `exclude`: tasks matching none of the values. Defaults to `and`. |
| `tagIds` | query | string |  | Comma-separated tag IDs (up to 100). `none` matches tasks with no value. |
| `tagMode` | query | and \| or \| exclude |  | How to combine `tagIds`. `and`: tasks matching any listed value, required together with the other conditions; `or`: tasks matching any listed value, where a match on any `or` condition is enough; `exclude`: tasks matching none of the values. Defaults to `and`. |
| `dueDateFrom` | query | integer |  | Return only tasks due at or after this time, in Unix epoch milliseconds. |
| `dueDateTo` | query | integer |  | Return only tasks due at or before this time, in Unix epoch milliseconds. |
| `hasDueDate` | query | 0 \| 1 \| true \| false |  | `true` returns only tasks with a due date, `false` only tasks without one (`true`, `false`, `1` or `0`). Omit for both. |
| `includeClosed` | query | 0 \| 1 \| true \| false |  | Whether to include tasks in a closed status: `true`, `false`, `1` or `0`. Defaults to `false`. |
| `overdueOnly` | query | 0 \| 1 \| true \| false |  | `true` returns only unfinished tasks whose due date has passed (closed tasks are always excluded). Defaults to `false`. |
| `result` | query | ids \| items |  | Shape of the response. `ids` returns matching task IDs; `items` returns task summaries, 30 per page. Defaults to `ids`. |
| `page` | query | integer |  | Page number, starting at 1. Used only when `result` is `items`. |

## Request

```sh
curl -X GET "https://<space>.repsona.com/api/search/task" \
  -H "Authorization: Bearer $REPSONA_API_KEY"
```

## Responses

- 200: Matching tasks ({ taskIds, truncated } or { items, hasMore })
- 400: Invalid query
- 401: Authentication is required

## Example response

```json
{
  "items": [
    {
      "id": 100434,
      "name": "Publish the release notes",
      "excerpt": "Post the release checklist results to the team wiki.",
      "projectFullName": "Website renewal",
      "statusName": null,
      "statusIsClosed": false,
      "dueDate": 1794267419499,
      "responsibleUser": {
        "id": 1101,
        "name": "aiko",
        "fullName": "Aiko Tanaka",
        "avatarUrl": null,
        "color": null,
        "state": "active"
      },
      "ballHoldingUser": null,
      "updatedAt": 1793662619499
    }
  ],
  "hasMore": false
}
```