Pagination and Sorting

Listing endpoints return paginated results with consistent pagination metadata. You can control page size, skip results, sort by different fields, and select specific response fields.

Offset Pagination

All listing endpoints use offset-based pagination with limit and offset query parameters.

# First page (20 results)
curl "https://lexbuild.dev/api/usc/documents?title_number=42"

# Second page
curl "https://lexbuild.dev/api/usc/documents?title_number=42&offset=20"

# Larger page size
curl "https://lexbuild.dev/api/usc/documents?title_number=42&limit=100"

Pagination Metadata

Every listing response includes a pagination object:

{
  "data": [ ... ],
  "meta": { ... },
  "pagination": {
    "total": 1542,
    "limit": 20,
    "offset": 0,
    "has_more": true,
    "next": "/api/usc/documents?title_number=42&sort=identifier&offset=20&limit=20"
  }
}

The next field provides a ready-to-use URL for the next page. You can use it to iterate through results without manually computing offsets:

# Follow the next link to page through results
curl "https://lexbuild.dev$(curl -s 'https://lexbuild.dev/api/usc/documents?title_number=42' | jq -r '.pagination.next')"

Cursor Pagination

As an alternative to offset-based pagination, listing endpoints also accept a cursor parameter for keyset pagination. The cursor value is the last document’s sort key from the previous page.

# First page
curl "https://lexbuild.dev/api/usc/documents?title_number=42&limit=20"

# Next page using cursor (value of the last document's sort field)
curl "https://lexbuild.dev/api/usc/documents?title_number=42&limit=20&cursor=/us/usc/t42/s1320"

Cursor pagination is more efficient than large offsets for deep result sets, since it does not require the database to skip over previously seen rows.

Sorting

Use the sort parameter to control the order of results. Prefix a field name with - for descending order.

# Sort by title number ascending
curl "https://lexbuild.dev/api/usc/documents?sort=title_number"

# Sort by title number descending
curl "https://lexbuild.dev/api/usc/documents?sort=-title_number"

# Sort FR documents by newest publication date
curl "https://lexbuild.dev/api/fr/documents?sort=-publication_date"

Default Sort Order

Each source has a different default sort:

Available Sort Fields

The sort fields vary by source. Use the sources endpoint to see the sortable_fields for each source.

USC and CFR:

Federal Register:

Field Selection

Use the fields query parameter to control which metadata fields are included in the response. This works on both listing endpoints and single-document endpoints.

Preset Values

Custom Field Lists

Pass a comma-separated list of field names to include only those fields:

curl "https://lexbuild.dev/api/usc/documents/t1/s1?fields=section_name,status,legal_status"

{
  "data": {
    "id": "usc-t1-s1",
    "identifier": "/us/usc/t1/s1",
    "source": "usc",
    "metadata": {
      "identifier": "/us/usc/t1/s1",
      "source": "usc",
      "section_name": "Words denoting number, gender, and so forth",
      "status": "in_force",
      "legal_status": "law"
    }
  },
  "meta": { ... }
}

The identifier and source fields are always included regardless of the field selection.

To include the body in a custom field list, add body as one of the fields:

curl "https://lexbuild.dev/api/usc/documents/t1/s1?fields=section_name,body"

Available Metadata Fields

Fields available depend on the source. Common fields across all sources:

USC-specific fields: title_number, title_name, section_number, section_name, chapter_number, chapter_name, subchapter_number, subchapter_name, positive_law, currency, source_credit

CFR-specific fields: title_number, title_name, section_number, section_name, chapter_number, chapter_name, part_number, part_name, agency, authority, regulatory_source, cfr_part, cfr_subpart

FR-specific fields: document_number, document_type, publication_date, agency, agencies, fr_citation, fr_volume, effective_date, comments_close_date, fr_action, docket_ids, cfr_references