Docs
SupportMy Brandwatch

Retrieving Filtered Mentions

Listing a filtered set of Mentions within your Query.

Suggest Edits

All Mention data calls can be filtered so that you can access specific parts of your data. You can do this by using Filters. To learn more about the available filters, please see Filters.

On this page we will show you:

Example Call - Filtering by Sentiment and Page Type

We want to restrict the data that is returned to be only tweets with neutral sentiment. We use two Filters for this:

  • pageType - In our particular case, we are interested in twitter.
  • sentiment - We want neutral Mentions to be returned.

The Filters are passed as parameters to the Mentions data call:
(For more information on making a basic Mentions call, see Retrieving Mentions)

curl -X GET 'https://api.brandwatch.com/projects/289733322/data/mentions?queryId=1998640329&startDate=2016-05-01&endDate=2016-05-02&page=0&pageSize=1&pageType=twitter&sentiment=neutral'

Here is one Mention that matches those Filters, out of a total of 57:

{
    "results": [
      {
            "resourceId": "05b7ea94bde2f66ae07b46ee8d076fa7",
            "accountType": "individual",
            "added": "2019-09-07T07:43:29.807+0000",
            "assignment": null,
            "author": null,
            "authorVerifiedType": null,
            "avatarUrl": null,
            "categories": [
                6745905
            ],
            "categoryDetails": [
                {
                    "id": "6745905",
                    "name": "Vodafone",
                    "parentId": "6745904",
                    "parentName": "Internet-Anbieter"
                }
            ],
            "checked": false,
            "city": "Stuttgart",
            "cityCode": "DEU.Baden-Wurttemberg.Stuttgart",
            "continent": "Europe",
            "continentCode": "EUROPE",
            "country": "Germany",
            "countryCode": "DEU",
            "region": "Baden-Württemberg",
            "regionCode": "DEU.Baden-Wurttemberg",
            "date": null,
            "displayUrls": null,
            "domain": "twitter.com",
            "engagement": 0.0,
            "expandedUrls": null,
            "facebookAuthorId": null,
            "facebookComments": 0,
            "facebookLikes": 0,
            "facebookRole": null,
            "facebookShares": 0,
            "facebookSubtype": null,
            "fullname": "YFYvonneAu1 (Yvonne Y. F. Kelle)",
            "gender": "female",
            "impressions": 0,
            "insightsHashtag": null,
            "insightsMentioned": null,
            "instagramCommentCount": 0,
            "instagramFollowerCount": 0,
            "instagramFollowingCount": 0,
            "instagramInteractionsCount": 0,
            "instagramLikeCount": 0,
            "instagramPostCount": 0,
            "interest": [],
            "language": "en",
            "lastAssignmentDate": null,
            "latitude": 0.0,
            "locationName": "Stuttgart, Baden-Wurttemberg, DEU",
            "longitude": 0.0,
            "matchPositions": [
                {
                    "start": 42,
                    "text": "Vodafone",
                    "length": 8
                },
                {
                    "start": 51,
                    "text": "internet",
                    "length": 8
                }
            ],
            "mediaFilter": null,
            "mediaUrls": [],
            "monthlyVisitors": 1308696000,
            "originalUrl": null,
            "pageType": "twitter",
            "priority": null,
            "professions": [],
            "queryId": 1999832640,
            "queryName": "Internet Anbieter",
            "reachEstimate": 0,
            "replyTo": null,
            "resourceType": "crimsonMonitor",
            "retweetOf": null,
            "sentiment": "neutral",
            "shortUrls": null,
            "snippet": null,
            "starred": false,
            "status": null,
            "subtype": null,
            "tags": [],
            "threadAuthor": null,
            "threadCreated": "2019-09-04T19:29:16.000+0000",
            "threadEntryType": null,
            "threadId": "1169331615333593089",
            "threadURL": null,
            "title": "http://twitter.com/1/statuses/1169390903821262848",
            "trackedLinkClicks": 0,
            "trackedLinks": null,
            "twitterAuthorId": null,
            "twitterFollowers": null,
            "twitterFollowing": null,
            "twitterPostCount": null,
            "twitterReplyCount": null,
            "twitterRetweets": null,
            "twitterRole": null,
            "twitterVerified": null,
            "updated": "2019-09-07T07:43:29.807+0000",
            "url": "http://twitter.com/1/statuses/1169390903821262848",
            "classifications": [
                {
                    "classifierId": "emotions",
                    "labelId": "Sadness",
                    "name": "Sadness",
                    "confidence": 0.021398207
                },
                {
                    "classifierId": "emotions",
                    "labelId": "Fear",
                    "name": "Fear",
                    "confidence": 0.067933984
                }
            ],
            "pageTypeName": "Twitter",
            "impact": 0.0
        }
    ],
    "resultsPage": 0,
    "resultsPageSize": 1,
    "resultsTotal": 225,
    "nextCursor": "AQ=AA=AWz-mFWg=MTk5OTgzMjY0MCEwNWI3ZWE5NGJkZTJmNjZhZTA3YjQ2ZWU4ZDA3NmZhNw",
    "startDate": "2019-09-01T00:00:00.000+0000",
    "endDate": "2019-09-05T00:00:00.000+0000"
}

Example Call - Filtering by Tags and Categories

You can also Filter your Mentions by the Categories and Tags that are assigned to them. For your Project, you will need to first retrieve the Categories or Tags that you wish to filter by. You will use the associated Category or Tag IDs in the following parameters:

  • tag - Return Mentions that are tagged with this Tag ID.
  • xtag - Return Mentions that are not tagged with this Tag ID.
  • category - Return Mentions that are tagged with this Category ID.
  • xcategory - Return Mentions that are not tagged with this Category ID.

For more information on how to find the appropriate ID, see Retrieving Categories and Retrieving Tags.

The Filters are passed as parameters to the Mentions data call. For example, to return Mentions that are tagged by Category ID 838322:
(For more information on making a basic Mentions call, see Retrieving Mentions)

curl -X GET 'https://api.brandwatch.com/projects/289733322/data/mentions?queryId=1998640329&startDate=2016-05-01&endDate=2016-05-02&page=0&pageSize=1&category=838322'

Here is one Mention that matches those Filters, out of total of 72:

{
  "resultsTotal": 72,
  "resultsPage": 0,
  "resultsPageSize": 1,
  "results": [
    {
      "accountType": null,
      "assignment": null,
      "author": "Najah Sameen",
      "authorVerifiedType": null,
      "avatarUrl": null,
      "categories": [838322],
      "categoryDetails": [
        {
          "id": "838322",
          "name": "Lips",
          "parentId": "838321",
          "parentName": "Beauty products"
        }
      ],
      "checked": false,
      "continent": "North America",
      "continentCode": "n-a",
      "country": "United States",
      "countryCode": "us",
      "region": null,
      "regionCode": null,
      "date": "2016-05-01T11:52:05.699+0000",
      "displayUrls": [],
      "domain": "www.indianbeautyforever.com",
      "facebookAuthorId": null,
      "facebookComments": 0,
      "facebookLikes": 0,
      "facebookRole": null,
      "facebookShares": 0,
      "facebookSubtype": null,
      "fullname": null,
      "gender": "unknown",
      "id": 99581066231,
      "impact": 39,
      "impressions": 0,
      "influence": 0,
      "insightsHashtag": [],
      "insightsMentioned": [],
      "instagramCommentCount": 0,
      "instagramFollowerCount": 0,
      "instagramFollowingCount": 0,
      "instagramLikeCount": 0,
      "instagramPostCount": 0,
      "interest": [],
      "language": "en",
      "lastAssignmentDate": null,
      "latitude": 0,
      "locationName": null,
      "longitude": 0,
      "matchPositions": [
        {
          "start": 133,
          "text": "oil",
          "length": 3
        },
        {
          "start": 150,
          "text": "oil",
          "length": 3
        },
        {
          "start": 178,
          "text": "moisturizing",
          "length": 12
        },
        {
          "start": 201,
          "text": "lips",
          "length": 4
        },
        {
          "start": 217,
          "text": "use",
          "length": 3
        },
        {
          "start": 227,
          "text": "at",
          "length": 2
        },
        {
          "start": 230,
          "text": "night",
          "length": 5
        },
        {
          "start": 247,
          "text": "lips",
          "length": 4
        }
      ],
      "mediaUrls": [],
      "monthlyVisitors": 0,
      "noteIds": [],
      "pageType": "news",
      "priority": null,
      "professions": [],
      "queryId": 1998640329,
      "queryName": "Makeup",
      "reach": 0,
      "replyTo": null,
      "resourceId": 99581066231,
      "resourceType": "page",
      "retweetOf": null,
      "sentiment": "positive",
      "shortUrls": [],
      "snippet": "Mango butter. These will hydrate and soften the dry lips. These lip balms also contain essential oils like macadamia nut oil, castor oil, carrot seed oil etc which are immensely moisturizing for flaky lips. I like to use these at night to give my lips boost of moisture. These lip moisturizer are mildly sweet in taste hence if you lick it you...",
      "starred": false,
      "state": null,
      "stateCode": null,
      "status": null,
      "subtype": null,
      "tags": [],
      "threadAuthor": null,
      "threadCreated": null,
      "threadEntryType": null,
      "threadId": "0",
      "threadURL": null,
      "title": "Island Kiss Tropical Lip Moisturisers Review - Indian Beauty Forever",
      "twitterAuthorId": null,
      "twitterFollowers": 0,
      "twitterFollowing": 0,
      "twitterPostCount": 0,
      "twitterReplyCount": 0,
      "twitterRetweets": 0,
      "twitterRole": null,
      "twitterVerified": false,
      "url": "http://www.indianbeautyforever.com/2016/04/island-kiss-tropical-lip-moisturisers-review.html?showComment=1462103525699",
    }
  ],
  "maximumId": 99581066231,
  "maximumIdInResult": 99581066231,
  "startDate": "2016-05-01T00:00:00.000+0000",
  "endDate": "2016-05-02T00:00:00.000+0000"
}

Example Call - Filtering by Entity ID

We want to restrict the data that is returned to be only mentions with entityId=29 (Spain). The entity IDs we refer to are the WikiData IDs which can be found in the WikiData URL (https://www.wikidata.org/wiki/Q29). We can use an entity ID (or comma-separated IDs) in the following parameter:

  • entityId - Return Mentions that contains selected entity ID(s)

The Filters are passed as parameters to the Mentions data call:
(For more information on making a basic Mentions call, see Retrieving Mentions)

curl -X GET 'https://api.brandwatch.com/projects/289733322/data/mentions?queryId=1998640329&startDate=2016-05-01&endDate=2016-05-02&page=0&pageSize=1&category=838322&entityId=29'

{
  "results": [
    {
      "accountType": "individual",
      "added": "2021-12-27T23:11:08.193+0000",
      "assignment": null,
      "author": "Cee_jayking",
      "authorVerifiedType": null,
      "avatarUrl": "https://audiences.brandwatch.com/api/audiences/v1/avatars/twitter/763729908?token=7d5c3d38a61e177b26bd25c440aec1352204f042087c35cf37c4a684f6c30353",
      "blogName": null,
      "categories": [],
      "categoryDetails": [],
      "checked": false,
      "city": null,
      "cityCode": null,
      "continent": null,
      "continentCode": null,
      "country": null,
      "countryCode": null,
      "region": null,
      "regionCode": null,
      "date": "2021-12-27T23:05:59.000+0000",
      "displayUrls": [],
      "domain": "twitter.com",
      "engagementType": "RETWEET",
      "expandedUrls": [],
      "facebookAuthorId": null,
      "facebookComments": 0,
      "facebookLikes": 0,
      "facebookRole": null,
      "facebookShares": 0,
      "facebookSubtype": null,
      "fullname": "Cee_jayking (TheEzeaka)",
      "gender": "unknown",
      "guid": "1475603900132696066",
      "impressions": 2329,
      "insightsHashtag": [],
      "insightsMentioned": [],
      "instagramCommentCount": 0,
      "instagramFollowerCount": 0,
      "instagramFollowingCount": 0,
      "instagramInteractionsCount": 0,
      "instagramLikeCount": 0,
      "instagramPostCount": 0,
      "interest": [
        "Music",
        "Sports"
      ],
      "itemReview": null,
      "language": "en",
      "lastAssignmentDate": null,
      "latitude": 0.0,
      "linkedinComments": 0,
      "linkedinEngagement": 0.0,
      "linkedinImpressions": 0,
      "linkedinLikes": 0,
      "linkedinShares": 0,
      "linkedinSponsored": false,
      "linkedinVideoViews": 0,
      "locationName": null,
      "longitude": 0.0,
      "matchPositions": [],
      "mediaFilter": null,
      "mediaUrls": [],
      "monthlyVisitors": 1414667000,
      "originalUrl": "http://twitter.com/Joshua_Ubeku/statuses/1473287738950574081",
      "pageType": "twitter",
      "parentPostId": null,
      "parentBlogName": null,
      "priority": null,
      "professions": [],
      "pubType": "Twitstream",
      "publisherSubType": null,
      "queryId": 2000744883,
      "queryName": "LM",
      "rating": null,
      "reachEstimate": 1451,
      "redditScore": null,
      "redditAuthorKarma": null,
      "redditAuthorAwardeeKarma": null,
      "redditAuthorAwarderKarma": null,
      "replyTo": null,
      "resourceType": "crimsonMonitor",
      "retweetOf": "http://twitter.com/Joshua_Ubeku/statuses/1473287738950574081",
      "rootPostId": null,
      "rootBlogName": null,
      "sentiment": "neutral",
      "shortUrls": [],
      "snippet": "RT @Joshua_Ubeku Messi - 7 Ballon d\u2019Or (1 player) Germany - 7 Ballon d\u2019Or (5 players) Portugal - 7 Ballon d\u2019Or (3 players) France - 6 Ballon d\u2019Or (4 players) England - 5 Ballon d\u2019Or (4 players) Italy - 5 Ballon d\u2019Or (5 players) Spain - 3 Ballon d\u2019Or (2 players) Think about this for a minute. \ud83d\ude02",
      "starred": false,
      "status": null,
      "subreddit": null,
      "subredditSubscribers": null,
      "subtype": null,
      "tags": [],
      "threadAuthor": "Joshua_Ubeku",
      "threadCreated": "2021-12-21T13:42:23.000+0000",
      "threadEntryType": "share",
      "threadId": "1473287738950574081",
      "threadURL": null,
      "title": "RT @Joshua_Ubeku Messi - 7 Ballon d\u2019Or (1 player)\nGermany - 7 Ballon d\u2019Or (5 players)\nPortugal - 7 Ballon d\u2019Or (3 players) \nFrance - 6 Ballon d\u2019Or (4 players)\nEngland - 5 Ballon d\u2019Or (4 players)\nItaly - 5 Ballon d\u2019Or (5 players)\nSpain - 3 Ballon d\u2019Or (2 players)\n\nThink about this for a minute. \ud83d\ude02",
      "twitterAuthorId": "763729908",
      "twitterFollowers": 2329,
      "twitterFollowing": 4989,
      "twitterPostCount": 22241,
      "twitterReplyCount": 0,
      "twitterRetweets": 0,
      "twitterRole": null,
      "twitterVerified": false,
      "updated": "2021-12-27T23:11:08.193+0000",
      "url": "http://twitter.com/Cee_jayking/statuses/1475603900132696066",
      "copyright": [],
      "weblogTitle": "Cee_jayking (TheEzeaka)",
      "classifications": [
        {
          "classifierId": "emotions",
          "labelId": "Surprise",
          "name": "Surprise",
          "confidence": 0.47631836
        }
      ],
      "pageTypeName": "Twitter",
      "impact": 3.9,
      "resourceId": "62f735be82110d58c691f9226f687429",
      "entityInfo": [
        {
          "entityId": 267245,
          "entityConfidence": "HIGH",
          "url": "https://www.wikidata.org/wiki/Q267245"
        },
        {
          "entityId": 183,
          "entityConfidence": "HIGH",
          "url": "https://www.wikidata.org/wiki/Q183"
        },
        {
          "entityId": 47762,
          "entityConfidence": "HIGH",
          "url": "https://www.wikidata.org/wiki/Q47762"
        },
        {
          "entityId": 142,
          "entityConfidence": "HIGH",
          "url": "https://www.wikidata.org/wiki/Q142"
        },
        {
          "entityId": 615,
          "entityConfidence": "HIGH",
          "url": "https://www.wikidata.org/wiki/Q615"
        },
        {
          "entityId": 38,
          "entityConfidence": "HIGH",
          "url": "https://www.wikidata.org/wiki/Q38"
        },
        {
          "entityId": 29,
          "entityConfidence": "HIGH",
          "url": "https://www.wikidata.org/wiki/Q29"
        },
        {
          "entityId": 166177,
          "entityConfidence": "MEDIUM",
          "url": "https://www.wikidata.org/wiki/Q166177"
        },
        {
          "entityId": 2736,
          "entityConfidence": "MEDIUM",
          "url": "https://www.wikidata.org/wiki/Q2736"
        },
        {
          "entityId": 208850,
          "entityConfidence": "LOW",
          "url": "https://www.wikidata.org/wiki/Q208850"
        }
      ]
    }
  ],
  "resultsTotal": 214,
  "scaledResultsTotal": 2924,
  "resultsPage": 0,
  "resultsPageSize": 1,
  "nextCursor": "AQ=AA=AX3-JLfY=MjAwMDc0NDg4MyE2MmY3MzViZTgyMTEwZDU4YzY5MWY5MjI2ZjY4NzQyOQ",
  "startDate": "2021-12-21T00:00:00.000+0000",
  "endDate": "2021-12-28T00:00:00.000+0000"
}

Updated over 1 year ago