# Pagination

The collection envelope, the page and link shapes, and the objects every collection shares.

## The collection envelope

As `GET /work-items` declares it, the widest form in the document.

- data (array of WorkItemList, required)
- meta (WorkItemsIndexMeta, required)
  - page (PageOptionalTotal, required)
    - per_page (integer, required): The page size that was applied.
    - next_cursor (string or null, required): Cursor for the next page, or null on the last one.
    - prev_cursor (string or null, required): Cursor for the previous page, or null on the first one.
    - total (integer or null, required): The total number of matching rows; null unless with_total=1 was sent.
  - warnings (array of object, optional): Non-fatal notes about this request. Switch on `code`, never on `detail`.
    - code (string, required): Machine-readable warning code. Switch on this, never on detail.
    - detail (string, required): Human-readable explanation.
    - pointer (string or null, optional): RFC 6901 pointer into the request body, where the warning is about a body field.
    - parameter (string or null, optional): The query-parameter name, brackets included, where the warning is about a parameter.
    - sunset (date (YYYY-MM-DD) or null, optional): Date the deprecated thing stops working.
    - replacement (string or null, optional): What to use instead.
- links (PageLinks, required)
  - self (url, required): This page.
  - next (url or null, required): The next page, or null on the last one.
  - prev (url or null, required): The previous page, or null on the first one.

## Page

- per_page (integer, required): The page size that was applied.
- next_cursor (string or null, required): Cursor for the next page, or null on the last one. Always null in page mode.
- prev_cursor (string or null, required): Cursor for the previous page, or null on the first one. Always null in page mode.
- total (integer, required): The total number of matching rows.
- current_page (integer or null, required): The page number this response answers, echoed from the request even when it exceeds last_page. Null when the request did not send page.
- last_page (integer or null, required): The highest page number that holds rows: ceil(total / per_page), and 1 on an empty collection. Null when the request did not send page.

## PageOptionalTotal

- per_page (integer, required): The page size that was applied.
- next_cursor (string or null, required): Cursor for the next page, or null on the last one.
- prev_cursor (string or null, required): Cursor for the previous page, or null on the first one.
- total (integer or null, required): The total number of matching rows; null unless with_total=1 was sent.

## PageLinks

- self (url, required): This page.
- next (url or null, required): The next page, or null on the last one.
- prev (url or null, required): The previous page, or null on the first one.

## Ref

A reference to a record by its id. The full object appears when the relation is included.

- id (integer, required)

## TagSummary

A tag, as referenced from another resource.

- id (integer, required): Unique identifier.
- title (string ≤ 255, required): Tag title as shown in the UI.

## TagSummaryInclude

- data (array of TagSummary ≤ 50, required)
- meta (object, required)
  - count (integer ≥ 0, optional)
  - truncated (boolean, required)

## Example
```json
{
  "data": [
    {
      "id": 1,
      "issue_key": "ACM-123",
      "title": "…",
      "priority": "highest",
      "due_date": "2026-03-04",
      "estimation": 1,
      "remaining_estimate": 1,
      "order": 1,
      "column_order": 1,
      "version": 1,
      "created_at": "2026-03-04T09:15:00Z",
      "updated_at": "2026-03-04T09:15:00Z",
      "project_id": 1,
      "task_id": 1,
      "workflow_status_id": 1,
      "work_type_id": 1,
      "sprint_id": 1,
      "parent_id": 1,
      "assignee_id": 1,
      "reporter_id": 1,
      "web_url": "…",
      "workflow_status": {
        "id": 1
      },
      "parent": null,
      "assignee": null,
      "reporter": {
        "id": 1
      },
      "work_type": {
        "id": 1
      },
      "sprint": null,
      "comments_count": 1,
      "subtasks_count": 1,
      "attachments_count": 1,
      "child_work_items_count": 1,
      "labels_count": 1,
      "drive_items_count": 1,
      "links_count": 1,
      "links": {
        "…": "8 fields of WorkItemLinks"
      },
      "…": "4 optional fields left out"
    }
  ],
  "meta": {
    "page": {
      "per_page": 1,
      "next_cursor": "…",
      "prev_cursor": "…",
      "total": 1
    },
    "warnings": [
      {
        "…": "6 fields of warnings"
      }
    ]
  },
  "links": {
    "self": "https://<your-url>/api/v2/work-items/1",
    "next": "https://<your-url>/api/v2/work-items/1",
    "prev": "https://<your-url>/api/v2/work-items/1"
  }
}
```