Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

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 sinceId 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, in addition to this tutorial.

Requesting Mentions for a given date range

In a similar manner to the other tutorial on 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:

Parameter
Value
Reasoning

pageSize

100

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.

orderBy

id

This orders the Mentions by their resourceId, which is a global counter incremented for every new Mention that we crawl.

orderDirection

asc

This changes the sort direction to ascending.

Here is the request as a cURL command:

curl -X GET https://api.brandwatch.com/projects/1998219784/data/mentions?queryId=1999038417&startDate=2017-07-31&endDate=2017-08-07&pageSize=100&orderBy=id&orderDirection=asc

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

{
  "resultsTotal": 3647,
  "resultsPage": 0,
  "resultsPageSize": 100,
  "results": [...],
  "maximumIdInResult": 148068801458,
  "startDate": "2017-07-31T00:00:00.000+0000",
  "endDate": "2017-08-07T00:00:00.000+0000",
  "maximumId": 148068801458
}

We can see from the result that there were a total of 3647 Mentions returned for that date range, and that the highest Resource ID among the 100 results returned as per our resultsPageSize setting is 148068801458 (indicated in the maximumIdInResult field). We can use this Resource ID to retrieve Mentions beyond the first 100 results.

Iterating through all available Mentions

After the first response, the client should store the Resource ID of the last Mention returned (identified by maximumIdInResult: 148068801458).

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

Parameter
Value
Reasoning

sinceId

148068801458

Specifies the lower boundary of the results returned (only results with a Resource ID over 148068801458 are returned)

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

curl -X GET https://api.brandwatch.com/projects/1998219784/data/mentions?queryId=1999038417&startDate=2017-07-31&endDate=2017-08-07&pageSize=100&orderBy=id&orderDirection=asc&sinceId=148068801458

This will return the next 100 results excluding the Mention with Resource ID 148068801458 which we have provided using in the sinceId parameter. The new response will look similar to this example:

{
  "resultsTotal": 3547,
  "resultsPage": 0,
  "resultsPageSize": 100,
  "results": [...],
  "maximumIdInResult": 148098141249,
  "startDate": "2017-07-31T00:00:00.000+0000",
  "endDate": "2017-08-07T00:00:00.000+0000",
  "maximumId": 148098141249
}

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

Paging through historical Mentions

Downloading data from your query by paging through it.