diff --git a/.changeset/standardize-pagination.md b/.changeset/standardize-pagination.md new file mode 100644 index 0000000000..535c08804f --- /dev/null +++ b/.changeset/standardize-pagination.md @@ -0,0 +1,21 @@ +--- +"adcontextprotocol": major +--- + +Standardize cursor-based pagination across all list operations. + +### Breaking Changes + +- **`list_creatives`**: Replace offset-based `limit`/`offset` with cursor-based `pagination` object +- **`tasks_list`**: Replace offset-based `limit`/`offset` with cursor-based `pagination` object +- **`list_property_lists`**: Move top-level `max_results`/`cursor` into nested `pagination` object +- **`get_property_list`**: Move top-level `max_results`/`cursor` into nested `pagination` object +- **`get_media_buy_artifacts`**: Move top-level `limit`/`cursor` into nested `pagination` object + +### Non-Breaking Changes + +- Add shared `pagination-request.json` and `pagination-response.json` schemas to `core/` +- Add optional `pagination` support to `list_accounts`, `get_products`, `list_creative_formats`, `list_content_standards`, and `get_signals` +- Update documentation for all affected operations + +All list operations now use a consistent pattern: `pagination.max_results` + `pagination.cursor` in requests, `pagination.has_more` + `pagination.cursor` + optional `pagination.total_count` in responses. diff --git a/docs/creative/task-reference/list_creative_formats.mdx b/docs/creative/task-reference/list_creative_formats.mdx index 622767c419..331aa24d29 100644 --- a/docs/creative/task-reference/list_creative_formats.mdx +++ b/docs/creative/task-reference/list_creative_formats.mdx @@ -42,6 +42,7 @@ See [list_creative_formats (Sales Agent)](/docs/media-buy/task-reference/list_cr | `min_height` | integer | No | Minimum height in pixels (inclusive) | | `is_responsive` | boolean | No | Filter for responsive formats (adapt to container size) | | `name_search` | string | No | Search formats by name (case-insensitive partial match) | +| `pagination` | object | No | Pagination: `max_results` (1-100, default 50) and `cursor` (opaque cursor from previous response) | ### Multi-Render Dimension Filtering diff --git a/docs/governance/content-standards/tasks/get_media_buy_artifacts.mdx b/docs/governance/content-standards/tasks/get_media_buy_artifacts.mdx index 7526caf06a..d4d81308ec 100644 --- a/docs/governance/content-standards/tasks/get_media_buy_artifacts.mdx +++ b/docs/governance/content-standards/tasks/get_media_buy_artifacts.mdx @@ -35,8 +35,7 @@ The buyer requests artifacts from the seller using the same media buy parameters | `package_ids` | array | No | Filter to specific packages | | `sampling` | object | No | Sampling parameters (defaults to media buy agreement) | | `time_range` | object | No | Filter to specific time period | -| `limit` | integer | No | Maximum artifacts to return (default: 1000) | -| `cursor` | string | No | Pagination cursor for large result sets | +| `pagination` | object | No | Pagination parameters (see below) | ### Sampling Options @@ -56,6 +55,15 @@ The buyer requests artifacts from the seller using the same media buy parameters | `recent` | Most recent deliveries first | | `failures_only` | Only artifacts that failed local evaluation | +### Pagination + +Uses higher limits than standard pagination because artifact result sets can be very large. + +| Parameter | Type | Default | Description | +|-----------|------|---------|-------------| +| `pagination.max_results` | integer | 1000 | Maximum artifacts per page (1-10,000) | +| `pagination.cursor` | string | - | Opaque cursor from a previous response | + ## Response **Schema**: [get-media-buy-artifacts-response.json](https://adcontextprotocol.org/schemas/v2/content-standards/get-media-buy-artifacts-response.json) @@ -173,7 +181,7 @@ for i, result in enumerate(validation["results"]): failures = seller_agent.get_media_buy_artifacts( media_buy_id="mb_nike_reddit_q1", sampling={"method": "failures_only"}, - limit=100 + pagination={"max_results": 100} ) # Verify these were correctly flagged diff --git a/docs/governance/content-standards/tasks/list_content_standards.mdx b/docs/governance/content-standards/tasks/list_content_standards.mdx index e8ebf674c9..4d15b28754 100644 --- a/docs/governance/content-standards/tasks/list_content_standards.mdx +++ b/docs/governance/content-standards/tasks/list_content_standards.mdx @@ -17,6 +17,7 @@ List available content standards configurations. | `countries` | array | No | Filter by ISO 3166-1 alpha-2 country codes (case-insensitive) | | `channels` | array | No | Filter by channels | | `languages` | array | No | Filter by ISO 639-1 or BCP 47 language tags (case-insensitive) | +| `pagination` | object | No | Pagination: `max_results` (1-100, default 50) and `cursor` (opaque cursor from previous response) | ## Response diff --git a/docs/governance/property/tasks/property_lists.mdx b/docs/governance/property/tasks/property_lists.mdx index e9efa7c120..e4612b8c5b 100644 --- a/docs/governance/property/tasks/property_lists.mdx +++ b/docs/governance/property/tasks/property_lists.mdx @@ -454,7 +454,9 @@ Retrieve a property list with optional resolution of filters. "arguments": { "list_id": "pl_abc123", "resolve": true, - "max_results": 100 + "pagination": { + "max_results": 1000 + } } } ``` @@ -474,11 +476,10 @@ The response returns a compact list of **identifiers only** (not full property o { "type": "domain", "value": "ft.com" }, { "type": "domain", "value": "theguardian.com" } ], - "total_count": 847, - "returned_count": 100, "pagination": { "has_more": true, - "cursor": "eyJvZmZzZXQiOjEwMH0=" + "cursor": "eyJvZmZzZXQiOjEwMH0=", + "total_count": 847 }, "resolved_at": "2026-01-03T17:15:00Z", "cache_valid_until": "2026-01-04T17:15:00Z" @@ -545,7 +546,9 @@ List all property lists accessible to the authenticated principal. "tool": "list_property_lists", "arguments": { "name_contains": "UK", - "max_results": 50 + "pagination": { + "max_results": 50 + } } } ``` @@ -574,10 +577,9 @@ List all property lists accessible to the authenticated principal. "property_count": 156 } ], - "total_count": 3, - "returned_count": 3, "pagination": { - "has_more": false + "has_more": false, + "total_count": 3 } } ``` diff --git a/docs/media-buy/task-reference/get_products.mdx b/docs/media-buy/task-reference/get_products.mdx index 6d067ce434..2bed870251 100644 --- a/docs/media-buy/task-reference/get_products.mdx +++ b/docs/media-buy/task-reference/get_products.mdx @@ -130,6 +130,7 @@ asyncio.run(discover_with_filters()) | `brand_manifest` | BrandManifest \| string | No | Brand information (inline object or URL). See [Brand Manifest](/docs/creative/brand-manifest) | | `filters` | Filters | No | Structured filters (see below) | | `property_list` | PropertyListRef | No | [AdCP 3.0] Reference to a property list for filtering. See [Property Lists](/docs/governance/property/tasks/property_lists) | +| `pagination` | PaginationRequest | No | Cursor-based pagination for large product catalogs (see below) | ### Filters Object @@ -188,6 +189,23 @@ Publishers may return proposals alongside products - structured media plans with | `brief_alignment` | string | How this proposal addresses the campaign brief | | `expires_at` | string | ISO 8601 timestamp when this proposal expires | +### Pagination + +For large product catalogs, use cursor-based pagination: + +| Request Parameter | Type | Description | +|---|---|---| +| `pagination.max_results` | integer | Maximum products per page (1-100, default: 50) | +| `pagination.cursor` | string | Cursor from previous response for next page | + +| Response Field | Type | Description | +|---|---|---| +| `pagination.has_more` | boolean | Whether more products are available | +| `pagination.cursor` | string | Cursor to pass for the next page | +| `pagination.total_count` | integer | Total matching products (optional, not all backends support this) | + +Pagination is optional. When omitted, the server returns all results (or a server-chosen default page). When the response includes `pagination.has_more: true`, pass `pagination.cursor` in the next request to get the next page. + ### Response Metadata | Field | Type | Description | diff --git a/docs/media-buy/task-reference/list_creatives.mdx b/docs/media-buy/task-reference/list_creatives.mdx index 46e76a9d7d..9fd2467956 100644 --- a/docs/media-buy/task-reference/list_creatives.mdx +++ b/docs/media-buy/task-reference/list_creatives.mdx @@ -137,13 +137,13 @@ Sort results by various fields with ascending or descending order: ## Pagination -Control result set size and navigation: +Control result set size with cursor-based pagination: ```json { "pagination": { - "limit": 50, // Max results per page (1-100, default: 50) - "offset": 0 // Results to skip (default: 0) + "max_results": 50, // Max results per page (1-100, default: 50) + "cursor": "eyJjcmVhdGVkX2RhdGUiOi4uLn0" // Cursor from previous response (omit for first page) } } ``` @@ -162,11 +162,9 @@ The response provides comprehensive creative data with optional enrichment: "filters_applied": ["format=video", "status=approved"] }, "pagination": { - "limit": 10, - "offset": 0, "has_more": true, - "total_pages": 3, - "current_page": 1 + "cursor": "eyJjcmVhdGVkX2RhdGUiOiIyMDI0LTAxLTE1VDEwOjMwOjAwWiJ9", + "total_count": 25 }, "creatives": [ { @@ -216,7 +214,7 @@ List all approved video creatives: "direction": "desc" }, "pagination": { - "limit": 20 + "max_results": 20 } } ``` @@ -255,7 +253,7 @@ Get creatives ready for assignment to new campaigns: "direction": "desc" }, "pagination": { - "limit": 50 + "max_results": 50 } } ``` @@ -347,7 +345,7 @@ Analyze creative uploads over a specific quarter: "direction": "asc" }, "pagination": { - "limit": 100 + "max_results": 100 } } ``` @@ -502,10 +500,10 @@ For queries returning very large result sets: - Use format and status filters to reduce result sets - Combine date ranges with other filters for efficiency -### 2. Paginate Appropriately +### 2. Paginate Appropriately - Avoid very large page sizes (>100) which may timeout -- Use offset-based pagination for consistent results -- Consider cursor-based pagination for very large libraries +- Use the `cursor` from the previous response to fetch the next page +- Cursor-based pagination handles data changes between requests ### 3. Field Selection - Request only needed fields using the `fields` parameter @@ -537,7 +535,7 @@ const response = await adcp.list_creatives({ }, sort: { field: "performance_score", direction: "desc" }, include_performance: true, - pagination: { limit: 10 } + pagination: { max_results: 10 } }); ``` diff --git a/docs/signals/tasks/get_signals.mdx b/docs/signals/tasks/get_signals.mdx index c0a1b9e62d..109319c5b9 100644 --- a/docs/signals/tasks/get_signals.mdx +++ b/docs/signals/tasks/get_signals.mdx @@ -20,6 +20,7 @@ The `get_signals` task returns both signal metadata and real-time deployment sta | `deliver_to` | DeliverTo | Yes | Deployment targets where signals need to be activated (see Deliver To Object below) | | `filters` | Filters | No | Filters to refine results (see Filters Object below) | | `max_results` | number | No | Maximum number of results to return | +| `pagination` | object | No | Pagination: `cursor` (opaque cursor from previous response) for paging through large result sets | ### Deliver To Object diff --git a/static/schemas/source/account/list-accounts-request.json b/static/schemas/source/account/list-accounts-request.json index 768317c4c9..2cf1d05323 100644 --- a/static/schemas/source/account/list-accounts-request.json +++ b/static/schemas/source/account/list-accounts-request.json @@ -11,6 +11,9 @@ "default": "active", "description": "Filter accounts by status" }, + "pagination": { + "$ref": "/schemas/core/pagination-request.json" + }, "context": { "$ref": "/schemas/core/context.json" }, diff --git a/static/schemas/source/account/list-accounts-response.json b/static/schemas/source/account/list-accounts-response.json index 9a59a966ec..a72f082f44 100644 --- a/static/schemas/source/account/list-accounts-response.json +++ b/static/schemas/source/account/list-accounts-response.json @@ -19,6 +19,9 @@ "$ref": "/schemas/core/error.json" } }, + "pagination": { + "$ref": "/schemas/core/pagination-response.json" + }, "context": { "$ref": "/schemas/core/context.json" }, @@ -53,7 +56,11 @@ "advertiser": "Publicis Media", "status": "active" } - ] + ], + "pagination": { + "has_more": false, + "total_count": 3 + } } }, { diff --git a/static/schemas/source/content-standards/get-media-buy-artifacts-request.json b/static/schemas/source/content-standards/get-media-buy-artifacts-request.json index 58f036ea66..52f7b24963 100644 --- a/static/schemas/source/content-standards/get-media-buy-artifacts-request.json +++ b/static/schemas/source/content-standards/get-media-buy-artifacts-request.json @@ -51,16 +51,23 @@ } } }, - "limit": { - "type": "integer", - "minimum": 1, - "maximum": 10000, - "default": 1000, - "description": "Maximum artifacts to return per request" - }, - "cursor": { - "type": "string", - "description": "Pagination cursor for fetching subsequent pages" + "pagination": { + "type": "object", + "description": "Pagination parameters. Uses higher limits than standard pagination because artifact result sets can be very large.", + "properties": { + "max_results": { + "type": "integer", + "minimum": 1, + "maximum": 10000, + "default": 1000, + "description": "Maximum number of artifacts to return per page" + }, + "cursor": { + "type": "string", + "description": "Opaque cursor from a previous response to fetch the next page" + } + }, + "additionalProperties": false }, "context": { "$ref": "/schemas/core/context.json" diff --git a/static/schemas/source/content-standards/get-media-buy-artifacts-response.json b/static/schemas/source/content-standards/get-media-buy-artifacts-response.json index fc1035b41b..21e84c183d 100644 --- a/static/schemas/source/content-standards/get-media-buy-artifacts-response.json +++ b/static/schemas/source/content-standards/get-media-buy-artifacts-response.json @@ -91,18 +91,7 @@ } }, "pagination": { - "type": "object", - "description": "Pagination information for large result sets", - "properties": { - "cursor": { - "type": "string", - "description": "Cursor for fetching the next page" - }, - "has_more": { - "type": "boolean", - "description": "Whether more results are available" - } - } + "$ref": "/schemas/core/pagination-response.json" }, "errors": { "not": {}, diff --git a/static/schemas/source/content-standards/list-content-standards-request.json b/static/schemas/source/content-standards/list-content-standards-request.json index fc5f246cac..dd14408cd0 100644 --- a/static/schemas/source/content-standards/list-content-standards-request.json +++ b/static/schemas/source/content-standards/list-content-standards-request.json @@ -20,6 +20,9 @@ "items": { "type": "string" }, "description": "Filter by ISO 3166-1 alpha-2 country codes" }, + "pagination": { + "$ref": "/schemas/core/pagination-request.json" + }, "context": { "$ref": "/schemas/core/context.json" }, diff --git a/static/schemas/source/content-standards/list-content-standards-response.json b/static/schemas/source/content-standards/list-content-standards-response.json index b436bc3f43..e4ffbc7736 100644 --- a/static/schemas/source/content-standards/list-content-standards-response.json +++ b/static/schemas/source/content-standards/list-content-standards-response.json @@ -18,6 +18,9 @@ "not": {}, "description": "Field must not be present in success response" }, + "pagination": { + "$ref": "/schemas/core/pagination-response.json" + }, "context": { "$ref": "/schemas/core/context.json" }, diff --git a/static/schemas/source/core/pagination-request.json b/static/schemas/source/core/pagination-request.json new file mode 100644 index 0000000000..425bb74e65 --- /dev/null +++ b/static/schemas/source/core/pagination-request.json @@ -0,0 +1,21 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/core/pagination-request.json", + "title": "Pagination Request", + "description": "Standard cursor-based pagination parameters for list operations", + "type": "object", + "properties": { + "max_results": { + "type": "integer", + "minimum": 1, + "maximum": 100, + "default": 50, + "description": "Maximum number of items to return per page" + }, + "cursor": { + "type": "string", + "description": "Opaque cursor from a previous response to fetch the next page" + } + }, + "additionalProperties": false +} diff --git a/static/schemas/source/core/pagination-response.json b/static/schemas/source/core/pagination-response.json new file mode 100644 index 0000000000..fb171306db --- /dev/null +++ b/static/schemas/source/core/pagination-response.json @@ -0,0 +1,24 @@ +{ + "$schema": "http://json-schema.org/draft-07/schema#", + "$id": "/schemas/core/pagination-response.json", + "title": "Pagination Response", + "description": "Standard cursor-based pagination metadata for list responses", + "type": "object", + "properties": { + "has_more": { + "type": "boolean", + "description": "Whether more results are available beyond this page" + }, + "cursor": { + "type": "string", + "description": "Opaque cursor to pass in the next request to fetch the next page. Only present when has_more is true." + }, + "total_count": { + "type": "integer", + "minimum": 0, + "description": "Total number of items matching the query across all pages. Optional because not all backends can efficiently compute this." + } + }, + "required": ["has_more"], + "additionalProperties": false +} diff --git a/static/schemas/source/core/tasks-list-request.json b/static/schemas/source/core/tasks-list-request.json index 9fc89581dd..34e3630047 100644 --- a/static/schemas/source/core/tasks-list-request.json +++ b/static/schemas/source/core/tasks-list-request.json @@ -106,24 +106,7 @@ "additionalProperties": true }, "pagination": { - "type": "object", - "description": "Pagination parameters", - "properties": { - "limit": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Maximum number of tasks to return" - }, - "offset": { - "type": "integer", - "minimum": 0, - "default": 0, - "description": "Number of tasks to skip" - } - }, - "additionalProperties": true + "$ref": "/schemas/core/pagination-request.json" }, "include_history": { "type": "boolean", @@ -175,7 +158,7 @@ "created_after": "2025-01-01T00:00:00Z" }, "pagination": { - "limit": 20 + "max_results": 20 } } }, diff --git a/static/schemas/source/core/tasks-list-response.json b/static/schemas/source/core/tasks-list-response.json index a30e6e0682..5d40ee37ce 100644 --- a/static/schemas/source/core/tasks-list-response.json +++ b/static/schemas/source/core/tasks-list-response.json @@ -73,10 +73,7 @@ "additionalProperties": true } }, - "required": [ - "total_matching", - "returned" - ], + "required": [], "additionalProperties": true }, "tasks": { @@ -137,35 +134,7 @@ } }, "pagination": { - "type": "object", - "description": "Pagination information", - "properties": { - "limit": { - "type": "integer", - "description": "Limit that was applied to this query", - "minimum": 1 - }, - "offset": { - "type": "integer", - "description": "Offset that was applied to this query", - "minimum": 0 - }, - "has_more": { - "type": "boolean", - "description": "Whether there are more tasks beyond this page" - }, - "next_offset": { - "type": "integer", - "description": "Offset to use for next page (only present if has_more is true)", - "minimum": 0 - } - }, - "required": [ - "limit", - "offset", - "has_more" - ], - "additionalProperties": true + "$ref": "/schemas/core/pagination-response.json" }, "context": { "$ref": "/schemas/core/context.json" diff --git a/static/schemas/source/creative/list-creative-formats-request.json b/static/schemas/source/creative/list-creative-formats-request.json index 348f5cc396..3e1b0fdd3f 100644 --- a/static/schemas/source/creative/list-creative-formats-request.json +++ b/static/schemas/source/creative/list-creative-formats-request.json @@ -62,6 +62,9 @@ "type": "string", "description": "Search for formats by name (case-insensitive partial match)" }, + "pagination": { + "$ref": "/schemas/core/pagination-request.json" + }, "context": { "$ref": "/schemas/core/context.json" }, diff --git a/static/schemas/source/creative/list-creative-formats-response.json b/static/schemas/source/creative/list-creative-formats-response.json index 30f86e8ab0..35cf5f6a8c 100644 --- a/static/schemas/source/creative/list-creative-formats-response.json +++ b/static/schemas/source/creative/list-creative-formats-response.json @@ -47,6 +47,9 @@ "$ref": "/schemas/core/error.json" } }, + "pagination": { + "$ref": "/schemas/core/pagination-response.json" + }, "context": { "$ref": "/schemas/core/context.json" }, diff --git a/static/schemas/source/index.json b/static/schemas/source/index.json index 3a6a7a4852..ce3e260720 100644 --- a/static/schemas/source/index.json +++ b/static/schemas/source/index.json @@ -66,6 +66,14 @@ "$ref": "/schemas/core/error.json", "description": "Standard error structure" }, + "pagination-request": { + "$ref": "/schemas/core/pagination-request.json", + "description": "Standard cursor-based pagination parameters for list request schemas" + }, + "pagination-response": { + "$ref": "/schemas/core/pagination-response.json", + "description": "Standard cursor-based pagination metadata for list response schemas" + }, "sub-asset": { "$ref": "/schemas/core/sub-asset.json", "description": "Sub-asset for multi-asset creative formats" diff --git a/static/schemas/source/media-buy/get-products-request.json b/static/schemas/source/media-buy/get-products-request.json index 4c3b3ba7a7..f609fb83e8 100644 --- a/static/schemas/source/media-buy/get-products-request.json +++ b/static/schemas/source/media-buy/get-products-request.json @@ -28,6 +28,9 @@ "$ref": "/schemas/core/property-list-ref.json", "description": "[AdCP 3.0] Reference to an externally managed property list. When provided, the sales agent should filter products to only those available on properties in the list." }, + "pagination": { + "$ref": "/schemas/core/pagination-request.json" + }, "context": { "$ref": "/schemas/core/context.json" }, diff --git a/static/schemas/source/media-buy/get-products-response.json b/static/schemas/source/media-buy/get-products-response.json index 8319a473de..ff388869cd 100644 --- a/static/schemas/source/media-buy/get-products-response.json +++ b/static/schemas/source/media-buy/get-products-response.json @@ -30,6 +30,9 @@ "type": "boolean", "description": "[AdCP 3.0] Indicates whether property_list filtering was applied. True if the agent filtered products based on the provided property_list. Absent or false if property_list was not provided or not supported by this agent." }, + "pagination": { + "$ref": "/schemas/core/pagination-response.json" + }, "context": { "$ref": "/schemas/core/context.json" }, diff --git a/static/schemas/source/media-buy/list-creative-formats-request.json b/static/schemas/source/media-buy/list-creative-formats-request.json index 75befbbfee..e1dea2135f 100644 --- a/static/schemas/source/media-buy/list-creative-formats-request.json +++ b/static/schemas/source/media-buy/list-creative-formats-request.json @@ -47,6 +47,9 @@ "type": "string", "description": "Search for formats by name (case-insensitive partial match)" }, + "pagination": { + "$ref": "/schemas/core/pagination-request.json" + }, "context": { "$ref": "/schemas/core/context.json" }, diff --git a/static/schemas/source/media-buy/list-creative-formats-response.json b/static/schemas/source/media-buy/list-creative-formats-response.json index dc47a2d2c5..7d7693b81b 100644 --- a/static/schemas/source/media-buy/list-creative-formats-response.json +++ b/static/schemas/source/media-buy/list-creative-formats-response.json @@ -47,6 +47,9 @@ "$ref": "/schemas/core/error.json" } }, + "pagination": { + "$ref": "/schemas/core/pagination-response.json" + }, "context": { "$ref": "/schemas/core/context.json" }, diff --git a/static/schemas/source/media-buy/list-creatives-request.json b/static/schemas/source/media-buy/list-creatives-request.json index 3df21c931f..f76ca80f74 100644 --- a/static/schemas/source/media-buy/list-creatives-request.json +++ b/static/schemas/source/media-buy/list-creatives-request.json @@ -26,24 +26,7 @@ "additionalProperties": true }, "pagination": { - "type": "object", - "description": "Pagination parameters", - "properties": { - "limit": { - "type": "integer", - "minimum": 1, - "maximum": 100, - "default": 50, - "description": "Maximum number of creatives to return" - }, - "offset": { - "type": "integer", - "minimum": 0, - "default": 0, - "description": "Number of creatives to skip" - } - }, - "additionalProperties": true + "$ref": "/schemas/core/pagination-request.json" }, "include_assignments": { "type": "boolean", @@ -118,7 +101,7 @@ "direction": "desc" }, "pagination": { - "limit": 20 + "max_results": 20 } } }, diff --git a/static/schemas/source/media-buy/list-creatives-response.json b/static/schemas/source/media-buy/list-creatives-response.json index 2a62717ff6..267884f4a7 100644 --- a/static/schemas/source/media-buy/list-creatives-response.json +++ b/static/schemas/source/media-buy/list-creatives-response.json @@ -39,47 +39,11 @@ } } }, - "required": [ - "total_matching", - "returned" - ], + "required": [], "additionalProperties": true }, "pagination": { - "type": "object", - "description": "Pagination information for navigating results", - "properties": { - "limit": { - "type": "integer", - "description": "Maximum number of results requested", - "minimum": 1 - }, - "offset": { - "type": "integer", - "description": "Number of results skipped", - "minimum": 0 - }, - "has_more": { - "type": "boolean", - "description": "Whether more results are available" - }, - "total_pages": { - "type": "integer", - "description": "Total number of pages available", - "minimum": 0 - }, - "current_page": { - "type": "integer", - "description": "Current page number (1-based)", - "minimum": 1 - } - }, - "required": [ - "limit", - "offset", - "has_more" - ], - "additionalProperties": true + "$ref": "/schemas/core/pagination-response.json" }, "creatives": { "type": "array", @@ -345,11 +309,8 @@ } }, "pagination": { - "limit": 50, - "offset": 0, "has_more": false, - "total_pages": 1, - "current_page": 1 + "total_count": 3 }, "creatives": [ { @@ -395,8 +356,6 @@ "returned": 1 }, "pagination": { - "limit": 50, - "offset": 0, "has_more": false }, "creatives": [ diff --git a/static/schemas/source/property/get-property-list-request.json b/static/schemas/source/property/get-property-list-request.json index 1fd852a761..6e7cdffe94 100644 --- a/static/schemas/source/property/get-property-list-request.json +++ b/static/schemas/source/property/get-property-list-request.json @@ -14,14 +14,23 @@ "description": "Whether to apply filters and return resolved identifiers (default: true)", "default": true }, - "max_results": { - "type": "integer", - "description": "Maximum identifiers to return (for large lists)", - "minimum": 1 - }, - "cursor": { - "type": "string", - "description": "Pagination cursor for large result sets" + "pagination": { + "type": "object", + "description": "Pagination parameters. Uses higher limits than standard pagination because property lists can contain tens of thousands of identifiers.", + "properties": { + "max_results": { + "type": "integer", + "minimum": 1, + "maximum": 10000, + "default": 1000, + "description": "Maximum number of identifiers to return per page" + }, + "cursor": { + "type": "string", + "description": "Opaque cursor from a previous response to fetch the next page" + } + }, + "additionalProperties": false }, "context": { "$ref": "/schemas/core/context.json" diff --git a/static/schemas/source/property/get-property-list-response.json b/static/schemas/source/property/get-property-list-response.json index 89ba3bfc5c..ba1725d1df 100644 --- a/static/schemas/source/property/get-property-list-response.json +++ b/static/schemas/source/property/get-property-list-response.json @@ -16,28 +16,8 @@ "$ref": "/schemas/core/identifier.json" } }, - "total_count": { - "type": "integer", - "description": "Total number of identifiers in resolved list" - }, - "returned_count": { - "type": "integer", - "description": "Number of identifiers returned in this response" - }, "pagination": { - "type": "object", - "description": "Pagination information", - "properties": { - "has_more": { - "type": "boolean", - "description": "Whether more results are available" - }, - "cursor": { - "type": "string", - "description": "Cursor for next page" - } - }, - "additionalProperties": false + "$ref": "/schemas/core/pagination-response.json" }, "resolved_at": { "type": "string", diff --git a/static/schemas/source/property/list-property-lists-request.json b/static/schemas/source/property/list-property-lists-request.json index 034c38e475..67a351abd8 100644 --- a/static/schemas/source/property/list-property-lists-request.json +++ b/static/schemas/source/property/list-property-lists-request.json @@ -13,15 +13,8 @@ "type": "string", "description": "Filter to lists whose name contains this string" }, - "max_results": { - "type": "integer", - "description": "Maximum lists to return", - "minimum": 1, - "default": 100 - }, - "cursor": { - "type": "string", - "description": "Pagination cursor" + "pagination": { + "$ref": "/schemas/core/pagination-request.json" }, "context": { "$ref": "/schemas/core/context.json" diff --git a/static/schemas/source/property/list-property-lists-response.json b/static/schemas/source/property/list-property-lists-response.json index f80b67ed17..9655f32ec0 100644 --- a/static/schemas/source/property/list-property-lists-response.json +++ b/static/schemas/source/property/list-property-lists-response.json @@ -12,28 +12,8 @@ "$ref": "/schemas/property/property-list.json" } }, - "total_count": { - "type": "integer", - "description": "Total number of lists matching criteria" - }, - "returned_count": { - "type": "integer", - "description": "Number of lists returned in this response" - }, "pagination": { - "type": "object", - "description": "Pagination information", - "properties": { - "has_more": { - "type": "boolean", - "description": "Whether more results are available" - }, - "cursor": { - "type": "string", - "description": "Cursor for next page" - } - }, - "additionalProperties": false + "$ref": "/schemas/core/pagination-response.json" }, "ext": { "$ref": "/schemas/core/ext.json" diff --git a/static/schemas/source/signals/get-signals-request.json b/static/schemas/source/signals/get-signals-request.json index 63d198140e..65ceeae985 100644 --- a/static/schemas/source/signals/get-signals-request.json +++ b/static/schemas/source/signals/get-signals-request.json @@ -52,6 +52,9 @@ "description": "Maximum number of results to return", "minimum": 1 }, + "pagination": { + "$ref": "/schemas/core/pagination-request.json" + }, "context": { "$ref": "/schemas/core/context.json" }, diff --git a/static/schemas/source/signals/get-signals-response.json b/static/schemas/source/signals/get-signals-response.json index ad045557e3..5493359cd0 100644 --- a/static/schemas/source/signals/get-signals-response.json +++ b/static/schemas/source/signals/get-signals-response.json @@ -94,6 +94,9 @@ "$ref": "/schemas/core/error.json" } }, + "pagination": { + "$ref": "/schemas/core/pagination-response.json" + }, "context": { "$ref": "/schemas/core/context.json" },