Pagination

The Mention Search endpoint (/projects/{project_id}/mentions/_search) returns up to 1,000 mentions per request, as specified by the size parameter.

To retrieve more mentions, make multiple requests and use the next parameter to paginate through the results.

How pagination works#

The next field in each _search response provides a cursor that identifies the next page of results. Copy the entire value, unchanged, into the next field of your subsequent request. The response to that request contains a new next value for the following page. Repeat this process until you have retrieved all the mentions you need.

The filters field must be included and remain unchanged in every paginated request. If you use the sort field, it must also remain unchanged.

Example#

Suppose we want to retrieve every mention containing the keyword "chocolate", ordered chronologically by publication date.

The first request fetches the initial page:

{
    "filters": {"synql": {"values": "chocolate"}},
    "sort": [{"field": "date", "order": "asc"}],
    "size": 1000
}

You can paginate with fewer than 1,000 mentions per request. However, requesting as many mentions as possible reduces the number of calls counted against your quota.

The response includes the first 1,000 mentions and the next value for fetching the second page:

{
    "total": 12345,
    "mentions": [/* 1000 mentions */],
    "next": ["tdq7kHkvFJ1u", 19246712505]
}

The value of next is an opaque array; it may contain any number of elements of any type, such as strings or numbers. Do not interpret or modify it.

To retrieve the second page, copy the next value from the response into the next request. Keep the filters, sort, and size fields unchanged:

{
    "filters": {"synql": {"values": "chocolate"}},
    "sort": [{"field": "date", "order": "asc"}],
    "size": 1000,
    "next": ["tdq7kHkvFJ1u", 19246712505]
}

The response includes the next page of mentions and a new next value. Use that value in the third request, and continue in the same way for each subsequent page.

When to stop?#

To retrieve all matching mentions, continue making requests until a response contains fewer mentions than the requested size.