---
agentTools:
  projectIndex: https://developers.brandwatch.com/llms.txt
---

# Paging through historical Mentions

Downloading data from your query by paging through it.

Another common integration use case is to request a large Mentions set within a date range and then iterate through them all. You may want to use this approach if you want to download a substantial dataset from your Query into your own integration.

In this tutorial, we'll take the following approach:

1. We will request for a batch of Mentions across a specified date range.
2. We will then use the `cursor` filter functionality to access additional results.

In this tutorial we will assume that the application has already logged in and has a token.
We also recommend that you read the section in our documentation about [Mentions](https://developers.brandwatch.com/docs/mentions), in addition to this tutorial.

[block:api-header]
{
  "type": "basic",
  "title": "Requesting Mentions for a given date range"
}
[/block]

In a similar manner to the other tutorial on [Polling for new Mentions](https://developers.brandwatch.com/docs/tutorial-polling-for-new-mentions), we'll begin by requesting the newest page of Mentions within a date range.

We'll use the following parameters to achieve this:

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Value",
    "h-2": "Reasoning",
    "0-0": "`pageSize`",
    "0-1": "100",
    "0-2": "This returns 100 Mentions per request. You can change this to a value between 1 and 5000 that suits you. Getting more than 5000 at a time is not possible.",
    "1-0": "`orderBy`",
    "1-1": "`date`",
    "1-2": "This orders the Mentions by their `date` (any valid `orderBy` should work fine here)",
    "2-0": "`orderDirection`",
    "2-1": "`asc`",
    "2-2": "This changes the sort direction to ascending."
  },
  "cols": 3,
  "rows": 3
}
[/block]

Here is the request as a cURL command:

[block:code]
{
  "codes": [
    {
      "code": "curl -X GET 'https://api.brandwatch.com/projects/1998232810/data/mentions?queryId=1999264284&startDate=2018-10-26&endDate=2018-11-09&pageSize=100&orderBy=date&orderDirection=asc'\n",
      "language": "curl"
    }
  ]
}
[/block]

This will return a list of Mentions. The following example response has had the Mentions removed for brevity.

[block:code]
{
  "codes": [
    {
      "code": "{\n  \"results\":[...],\n  \"resultsPage\":0,\n  \"resultsPageSize\":100,\n  \"resultsTotal\":234,\n  \"nextCursor\":\"AQ=AA=AWbKauTY=Mlz58Vk=dypaHA\",\n  \"startDate\":\"2018-10-26T00:00:00.000+0000\",\n  \"endDate\":\"2018-11-09T00:00:00.000+0000\",\n  \"maximumIdInResult\":217365452890,\n  \"maximumId\":217365452890\n}",
      "language": "json"
    }
  ]
}
[/block]

We can see from the result that there were a total of 234 Mentions returned for that date range and there is also a `nextCursor` field containing a cursor value. We can use this cursor value to retrieve Mentions beyond the first 100 results.

[block:api-header]
{
  "type": "basic",
  "title": "Iterating through all available Mentions"
}
[/block]

After the first response, the client should store the cursor value returned (identified by `nextCursor: "AQ=AA=AWbKauTY=Mlz58Vk=dypaHA"`).  You can think of the cursor like a bookmark, that we can use to remember the previous position in the results.

With this cursor we can retrieve additional Mentions using the below parameter:

[block:parameters]
{
  "data": {
    "h-0": "Parameter",
    "h-1": "Value",
    "h-2": "Reasoning",
    "0-0": "`cursor`",
    "0-1": "AQ=AA=AWbKauTY=Mlz58Vk=dypaHA",
    "0-2": "Specifies the \"cursor\" position to start returning results from"
  },
  "cols": 3,
  "rows": 1
}
[/block]

With this parameter we can now retrieve the next 100 Mentions:

[block:code]
{
  "codes": [
    {
      "code": "curl -X GET 'https://api.brandwatch.com/projects/1998232810/data/mentions?queryId=1999264284&startDate=2018-10-26&endDate=2018-11-09&pageSize=100&orderBy=date&orderDirection=asc&cursor=AQ%3DAA%3DAWbKauTY%3DMlz58Vk%3DdypaHA'",
      "language": "curl"
    }
  ]
}
[/block]

Nb. the cursor has been URL encoded in the request above (`AQ%3DAA%3DAWbKauTY%3DMlz58Vk%3DdypaHA`).
This will return the next 100 results. The new response will look similar to this example:

[block:code]
{
  "codes": [
    {
      "code": "{\n  \"results\":[...],\n  \"resultsPage\":1,\n  \"resultsPageSize\":100,\n  \"resultsTotal\":234,\n  \"prevCursor\":\"AQ=AQ=AWbKbU4I=Ml2eY8E=dypaHA\",\n  \"nextCursor\":\"AQ=AA=AWbldT7V=Mpojoo8=dypaHA\",\n  \"startDate\":\"2018-10-26T00:00:00.000+0000\",\n  \"endDate\":\"2018-11-09T00:00:00.000+0000\",\n  \"maximumIdInResult\":217349261612,\n  \"maximumId\":217349261612\n}",
      "language": "json"
    }
  ]
}
[/block]

We can now repeat this process with the new `nextCursor` value, until no more results are returned, to retrieve all available Mentions.