--- agentTools: projectIndex: https://developers.brandwatch.com/llms.txt --- # Retrieving Mentions Listing the Mentions within your Query. ## Required Parameters There are three required parameters when retrieving Mentions: [block:parameters] { "data": { "h-0": "Parameter", "h-1": "Definition", "h-2": "Accepted Values", "0-0": "`queryId` / `queryGroupId`", "0-1": "The ID of the Query or Query Group that contains the Mentions.", "0-2": "int (can be specified multiple times) \n(Learn how to retrieve your [Query ID](https://developers.brandwatch.com/docs/retrieving-queries) or [Query Group ID](https://developers.brandwatch.com/docs/retrieving-query-groups)", "1-0": "`startDate`", "1-1": "The beginning of the date range that contains the Mentions.", "1-2": "Format: \"YYYY-MM-DD'T'hh:mm:ss:xx.xx+xxxx\" \n \nNote: you can specify the time zone by replacing `+xxxx` with the ISO UTC offset, e.g `-0500` for New York standard time. **Important:** The character `+` should be URL encoded to `%2B`", "2-0": "`endDate`", "2-1": "The end of the date range that contains the Mentions.", "2-2": "Format: \"YYYY-MM-DD'T'hh:mm:ss:xx.xx+xxxx\" \n \nNote: you can specify the time zone by replacing `+xxxx` with the ISO UTC offset, e.g `-0500` for New York standard time. **Important:** The character `+` should be URL encoded to `%2B`" }, "cols": 3, "rows": 3, "align": [ "left", "left", "left" ] } [/block] ## Pagination You can control the pagination by passing the following additional parameters. | Parameter | Definition | Accepted Values | | :--------- | :--------------------------------------------------- | :------------------------------- | | `pageSize` | The number of Mentions on each page of the response. | An integer from 1-5000 | | `page` | The page to retrieve, indexed from 0. | An integer, index starting at 0. | There is a limit of 10,000 mentions that can be retrieved using `page` and `pageSize` alone. To see how to retrieve more mentions see the tutorial [Paging through historical Mentions](https://developers.brandwatch.com/docs/tutorial-paging-through-historical-mentions). ## Ordering You also have the option to control the ordering by passing additional parameters: | Parameter | Definition | Accepted Values | | :--------------- | :--------------------------------------------- | :------------------------------------------------------------------------- | | `orderBy` | The field you'd like to order the Mentions by. | [List of options](https://developers.brandwatch.com/docs/sorting-mentions) | | `orderDirection` | The direction to order the Mentions. | "desc" (descending) or "asc" (ascending) | ## Example Call An example call for Mentions in the Project with ID `289733322` is below.\ (Click [here](https://developers.brandwatch.com/docs/retrieving-projects) to learn how to get your Project ID) ```curl curl -X GET 'https://api.brandwatch.com/projects/289733322/data/mentions?queryId=348973733&startDate=2016-05-01&endDate=2016-05-02&pageSize=1&page=0' ``` The response will look like this: ```json JSON { "results": [ { "accountType": "individual", "added": "2019-10-10T17:48:54.588+0000", "assignment": null, "author": null, "authorVerifiedType": null, "avatarUrl": null, "blogName": null, "blueskyAuthorId": null, "blueskyFollowers": 0, "blueskyFollowing": 0, "blueskyLikes": 0, "blueskyPosts": 0, "blueskyQuotes": 0, "blueskyReplies": 0, "blueskyReposts": 0, "categories": [ 8151046, 7594551 ], "categoryDetails": [ { "id": "8151046", "name": "Negative", "parentId": "8151044", "parentName": "Custom Sentiment" }, { "id": "7594551", "name": "BBC Radio", "parentId": "7594548", "parentName": "BBC Programs" } ], "checked": false, "city": null, "cityCode": null, "continent": "Europe", "continentCode": "EUROPE", "country": "United Kingdom", "countryCode": "GBR", "region": null, "regionCode": null, "date": "2020-06-29T22:45:43.000+0000", "dailyVisitors": 1973, "displayUrls": null, "domain": "twitter.com", "expandedUrls": null, "facebookAuthorId": null, "facebookComments": 0, "facebookLikes": 0, "facebookRole": null, "facebookShares": 0, "facebookSubtype": null, "fullname": "edwards0819 (Jan Edwards)", "gender": "unknown", "impressions": 48, "insightsHashtag": null, "insightsMentioned": null, "instagramCommentCount": 0, "instagramFollowerCount": 0, "instagramFollowingCount": 0, "instagramInteractionsCount": 0, "instagramLikeCount": 0, "instagramPostCount": 0, "interest": [], "itemReview": null, "language": "en", "lastAssignmentDate": null, "latitude": 0, "linkedinComments": 0, "linkedinEngagement": 0, "linkedinImpressions": 0, "linkedinLikes": 0, "linkedinShares": 0, "linkedinVideoViews": 0, "locationName": "GBR", "longitude": 0, "matchPositions": [ { "start": 213, "text": "BBCR4today", "length": 10 } ], "mediaFilter": null, "mediaUrls": [ "http://pbs.twimg.com/media/EDPcH9iW4AMxgfR.jpg" ], "monthlyVisitors": 1308696000, "originalUrl": null, "pageType": "twitter", "parentPostId": null, "parentBlogName": null, "priority": null, "professions": [], "pubType": null, "publisherSubType": null, "queryId": 1999933037, "queryName": "BBC", "rating": null, "reachEstimate": 0, "replyTo": null, "resourceType": "crimsonMonitor", "retweetOf": null, "rootPostId": null, "rootBlogName": null, "sentiment": "neutral", "shortUrls": null, "snippet": null, "starred": false, "status": null, "subtype": null, "tags": [], "threadAuthor": null, "threadCreated": "2019-08-30T19:25:43.000+0000", "threadEntryType": null, "threadId": "1167518780588810240", "threadURL": null, "title": "http://twitter.com/1/statuses/1168312574590509056", "twitterAuthorId": null, "twitterFollowers": null, "twitterFollowing": null, "twitterPostCount": null, "twitterReplyCount": null, "twitterRetweets": null, "twitterRole": null, "twitterVerified": null, "updated": "2019-10-10T17:48:54.588+0000", "url": "http://twitter.com/1/statuses/1168312574590509056", "copyright": [], "weblogTitle": null, "tiktokComments": 0, "tiktokLikes": 0, "tiktokShares": 0, "classifications": [ { "classifierId": "emotions", "labelId": "Sadness", "name": "Sadness", "confidence": 0.43600535 } ], "pageTypeName": "Twitter", "impact": 0, "imageInfo": [ { "url": "http://pbs.twimg.com/media/EbJDdEeWoAUwYX.jpg", "imageDimensions": { "height": 675, "width": 1200 }, "dominantColor": "#082A5E", "objects": [ { "id": 4105, "confidence": 0.9748200178146362 } ], "scenes": [ { "id": 3750, "confidence": 0.9648399949073792 }, { "id": 3779, "confidence": 0.9537400007247925 } ], "logoImagesGroupId": "3737363464336336656563313631386634363765646630366536666633623432" } ], "resourceId": "c54d12f5107496bac30b5ddc3478bbab", "entityInfo" : [ { "entityConfidence" : "HIGH", "entityId" : 19809, "url" : "https://www.wikidata.org/wiki/Q19809" }, { "entityConfidence" : "MEDIUM", "entityId" : 4759878, "url" : "https://www.wikidata.org/wiki/Q4759878" } ] } ], "resultsTotal": 16332, "scaledResultsTotal": 142452, "resultsPage": 0, "resultsPageSize": 1, "nextCursor": "AQ=AA=AWzvRWQw=MTk5OTkzMzAzNyFjNTRkMTJmNTEwNzQ5NmJhYzMwYjVkZGMzNDc4YmJhYg", "startDate": "2019-09-01T00:00:00.000+0000", "endDate": "2019-09-02T00:00:00.000+0000" } ``` For definitions of the returned fields, see [Mention Field Definitions](https://developers.brandwatch.com/docs/mention-metadata-field-definitions). ## Full Text If you wish to receive the full text of a Mention rather than just a snippet, then you can use the `fulltext` endpoint: ```curl curl -X GET 'https://api.brandwatch.com/projects/289733322/data/mentions/fulltext?queryId=348973733&startDate=2016-05-01&endDate=2016-05-02&pageSize=1&page=0' ``` > ❗️ Data restrictions > > For some content sources, there may be restrictions due to data compliance. Please see [Data Restrictions](https://developers.brandwatch.com/docs/data-restrictions) for more information. ## Encoding The Consumer Research API will return data as it was found and does not apply any additional encoding or sanitization before returning it through the Mentions endpoint. It is your responsibility to make sure that it is formatted correctly for display in your own application.