> ## Documentation Index
> Fetch the complete documentation index at: https://wordsmithai.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# List Tasks

> List and filter tasks you have access to.

Returns a cursor-paginated page of tasks, ordered by priority, then due date, then most recently created. Results are scoped to what your API key's user can see.

Pass the `cursor` from a response to fetch the next page; a null `cursor` means you have reached the end. **Keep `limit` the same for every page of a walk** — the cursor is tied to the page size it was issued with, so changing it mid-walk skips or repeats rows. Archived and draft tasks are excluded unless you filter for them.

## Query parameters

<ParamField query="query" type="string">
  Free-text search across title, description, additional context and comment text.
</ParamField>

<ParamField query="status" type="string">
  Comma-separated: `not_started`, `in_progress`, `waiting_on_external`, `completed`.
</ParamField>

<ParamField query="priority" type="string">
  One of `no_priority`, `urgent`, `high`, `medium`, `low`.
</ParamField>

<ParamField query="assigned_to" type="string">
  User id — only tasks assigned to this person.
</ParamField>

<ParamField query="involving" type="string">
  User id — tasks this person is involved in at all (assignee, creator or shared).
</ParamField>

<ParamField query="team_id" type="string">
  Task team id.
</ParamField>

<ParamField query="tags" type="string">
  Comma-separated tag list.
</ParamField>

<ParamField query="complete_by_from" type="string">
  ISO 8601 timestamp, e.g. `2026-01-01` or `2026-01-01T09:00:00Z` — only tasks due at or after it.
</ParamField>

<ParamField query="complete_by_to" type="string">
  ISO 8601 timestamp — only tasks due at or before it.
</ParamField>

<ParamField query="cursor" type="string">
  Pagination cursor from a previous response.
</ParamField>

<ParamField query="limit" type="string">
  Page size, 1–100. Defaults to 20. Values below 1 are rejected.
</ParamField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request GET 'https://api.wordsmith.ai/api/v1/tasks' \
  --header 'Authorization: Bearer YOUR_API_KEY'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch("https://api.wordsmith.ai/api/v1/tasks", {
    method: "GET",
    headers: {
      Authorization: "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
  });
  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  url = "https://api.wordsmith.ai/api/v1/tasks"
  headers = {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
  }

  response = requests.get(url, headers=headers)
  print(response.json())
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "items": [
      {
        "id": "9f8e7d6c-5b4a-3210-9876-543210fedcba",
        "display_id": "#12",
        "task_number": 12,
        "title": "Review the Acme NDA",
        "description": "Check the indemnity and termination clauses.",
        "additional_context": "Counterparty has pushed back twice on liability caps.",
        "status": "in_progress",
        "priority": "high",
        "team": {
          "id": "1a2b3c4d-5e6f-7081-9200-aabbccddeeff",
          "name": "Legal"
        },
        "creator": {
          "id": "11111111-2222-3333-4444-555555555555",
          "name": "Jane Doe",
          "email": "jane@example.com"
        },
        "assigned_to": {
          "id": "11111111-2222-3333-4444-555555555555",
          "name": "Jane Doe",
          "email": "jane@example.com"
        },
        "assigned_agent": null,
        "assigned_team": null,
        "matter": null,
        "complete_by": "2026-01-01T00:00:00Z",
        "tags": [
          "nda",
          "urgent"
        ],
        "visibility": "customer",
        "archived": false,
        "draft": false,
        "involved_people": [
          {
            "id": "11111111-2222-3333-4444-555555555555",
            "name": "Jane Doe",
            "email": "jane@example.com",
            "role": "assignee",
            "access_level": "write"
          }
        ],
        "shared_teams": [],
        "linked_items": [],
        "input_files": [],
        "output_files": [],
        "created_at": "2025-12-31T00:00:00Z",
        "updated_at": "2025-12-31T01:00:00Z"
      }
    ],
    "cursor": "20"
  }
  ```
</ResponseExample>