Phân trang

Duyệt danh sách bằng con trỏ — limit, cursor, before, sort, dir và q; các lỗi CURSOR_* khi đổi hướng giữa chừng; và vì sao danh sách không kèm tổng số.

Một trang trông như thế nào

Mọi danh sách trả về cùng một dạng:

{
  "items": [ … ],
  "next_cursor": "…",
  "prev_cursor": null
}

next_cursor — gửi lại để lấy trang kế tiếp; null khi đã hết.
prev_cursor — gửi lại để quay về trang trước; null ở trang đầu tiên.

Con trỏ là chuỗi mờ (opaque): đừng giải mã, đừng tự dựng. Chỉ gửi lại đúng giá trị server đã trả.

Tham số

Tham số	Ý nghĩa
`limit`	Số mục mỗi trang, từ `1` đến `200`; mặc định `50`.
`cursor`	Đi tiếp: giá trị `next_cursor` của trang trước.
`before`	Đi lùi: giá trị `prev_cursor`. Không gửi cùng lúc với `cursor`.
`sort`	Sắp xếp theo gì. Giá trị hợp lệ tùy từng danh sách.
`dir`	`asc` hoặc `desc`. Không gửi thì dùng chiều mặc định của cách sắp xếp.
`q`	Tìm kiếm văn bản. Mỗi danh sách tìm trên những trường riêng.

Mọi danh sách nhận đủ sáu tham số này: trong chuỗi truy vấn, hoặc trong thân yêu cầu với POST …/records/query, nơi q nằm trong filter. Tài liệu tham chiếu ghi các giá trị sort của từng danh sách, chiều mặc định của từng giá trị, và q khớp với gì.

Ví dụ duyệt hồ sơ của một thực thể, mới cập nhật trước:

curl -sS -G "$ORIGIN/api/v1/entities/$ENTITY_ID/records" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "sort=updated_at" \
  --data-urlencode "dir=desc"

# Trang kế tiếp: thêm next_cursor, giữ nguyên limit, sort, dir và mọi bộ lọc
curl -sS -G "$ORIGIN/api/v1/entities/$ENTITY_ID/records" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  --data-urlencode "limit=50" \
  --data-urlencode "sort=updated_at" \
  --data-urlencode "dir=desc" \
  --data-urlencode "cursor=$NEXT_CURSOR"

Tham số bị từ chối

Server đối chiếu chuỗi truy vấn với đúng những tham số danh sách khai báo. Tham số nó không nhận thì bị từ chối, không bị bỏ qua:

Trạng thái	Mã (`type`)	Khi nào
`400`	`INVALID_QUERY_PARAMETER`	`limit` ngoài khoảng `1`–`200`, một giá trị `sort` hay `dir` mà danh sách không nhận, hoặc một bộ lọc sai kiểu — ví dụ một boolean khác `true` và `false`, hay một id sai định dạng.
`400`	`UNKNOWN_QUERY_PARAMETER`	Một tham số mà danh sách không khai báo — ví dụ một tên gõ sai.

field_errors nêu tên từng tham số bị từ chối. Nhờ vậy một bộ lọc gõ sai không bao giờ lặng lẽ trả về một danh sách rộng hơn điều bạn hỏi. Xem thêm Lỗi.

Đổi sắp xếp hoặc bộ lọc giữa chừng

Một con trỏ gắn chặt với cách sắp xếp và bộ lọc đã sinh ra nó. Đổi một trong hai giữa lúc đang duyệt thì yêu cầu bị từ chối:

Trạng thái	Mã (`type`)	Khi nào
`400`	`CURSOR_SORT_MISMATCH`	Đổi `sort` hoặc `dir` giữa chừng.
`400`	`CURSOR_FILTERS_CHANGED`	Đổi bộ lọc giữa chừng.
`400`	`CURSOR_INVALID`	Con trỏ hỏng, hoặc gửi cả `cursor` lẫn `before`.

Khi gặp các lỗi này, hãy bắt đầu lại từ trang đầu với tham số mới.

Danh sách không kèm tổng số

Danh sách không trả về tổng số mục. Khi cần một con số, hãy gọi thao tác đếm riêng, ví dụ POST /api/v1/entities/{entity_id}/records/count:

curl -sS -X POST "$ORIGIN/api/v1/entities/$ENTITY_ID/records/count" \
  -H "Authorization: Bearer $AGENTFLOW_KEY" \
  -H "Content-Type: application/json" \
  -d '{"filter": {"q": "PO-1001"}}'

{ "count": 12, "capped": false }

capped: true nghĩa là con số thật lớn hơn hoặc bằng count: lượt đếm đã chạm ngưỡng.