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

# List Project To-dos

> Read the catalog, roster, assignments, and pre-pagination summary for a job or one contract.

Returns the employer view (catalog, roster, all assignments) for a `jobId`, or the AI trainer view (their own effective list and history) for a `contractId` the token owns. An employer token with a `contractId` gets a job-view drilldown for that contract. Requires `project_todos:read`.

<ParamField query="jobId" type="string">
  Employer view of one job. Required unless `contractId` is set.
</ParamField>

<ParamField query="contractId" type="string">
  One contract's list — the AI trainer's own view, or an employer drilldown.
</ParamField>

<ParamField query="status" type="string">
  Filter assignments: `OPEN`, `IN_PROGRESS`, `SUBMITTED`, `COMPLETED`, `RETURNED`, `WAIVED`, `CLOSED`, or `SUPERSEDED`.
</ParamField>

<ParamField query="categoryId" type="string">Filter to one category.</ParamField>
<ParamField query="itemId" type="string">Filter to one logical item.</ParamField>

<ParamField query="assignedTo" type="string">
  Employer job view: filter assignments to one contract ID. Requires `jobId`.
</ParamField>

<ParamField query="needsReview" type="boolean">
  `true` returns only `SUBMITTED` assignments awaiting employer review; `false` excludes them.
</ParamField>

<ParamField query="includeArchived" type="boolean">
  Include archived items and categories in the employer catalog for auditing.
</ParamField>

<ParamField query="cursor" type="string">Resume from a previous `nextCursor`.</ParamField>
<ParamField query="limit" type="number">Page size, 1–100 (default 25).</ParamField>

Conflicting filters fail with `400` — for example `needsReview=true` with a non-`SUBMITTED` `status`, or `assignedTo` without `jobId`.

## Response

* `enabled` — when the job has not enabled Project To-dos, the surface reads as inert: empty catalog and assignments, history retained.
* `categories` and a flat `items` array for direct parsing, each item with its `archivedAt`, future-hire flag, and per-person progress counts.
* `people` — the employer roster with contract ID, user ID, and a masked display name. Personal emails never appear.
* `assignments` — paginated; each carries its immutable item version, status, due and blocking times, and append-only evidence and events.
* `summary` — counts computed over the complete filtered result before pagination: items, archived items, assignments, open, completed, needs-review, and returned.
* Worker views include `blocking` — whether required items currently gate project work.