X (Twitter) Insights

You can receive aggregated breakdowns of X metadata via the four endpoints that power our X Insights component.

These endpoints are very similar, and accept all of our usual Filters.

Required Parameters

Parameter	Definition	Accepted Values
`queryId` / `queryGroupId`	The ID of the Query or Query Group that contains the Mentions for which you'd like to see.	int (Learn how to retrieve your Query ID or Query Group ID
`startDate`	The beginning of the date range that contains the Mentions.	"YYYY-MM-DD'T'hh:mm:ss.xxx+xxxx"
`endDate`	The end of the date range that contains the Mentions.	"YYYY-MM-DD'T'hh:mm:ss.xxx+xxxx"

Note: 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

X Hashtags

curl -X GET 'https://api.brandwatch.com/projects/397382923/data/hashtags?queryId=1834636622&startDate=2023-11-11&endDate=2023-11-18'

The result will look like the following:

{
    "results": [
        {
            "name": "#battenwear",
            "label": null,
            "volume": 27,
            "tweets": 27,
            "retweets": 0,
            "impressions": 0,
            "sentiment": {
                "negative": 27,
                "neutral": 207,
                "positive": 11
            }
        },
        {
            "name": "#menswear",
            "label": null,
            "volume": 6,
            "tweets": 6,
            "retweets": 0,
            "impressions": 0,
            "sentiment": {
                "negative": 27,
                "neutral": 207,
                "positive": 11
            }
        },
        {
            "name": "#outdoor",
            "label": null,
            "volume": 5,
            "tweets": 5,
            "retweets": 0,
            "impressions": 0,
            "sentiment": {
                "negative": 27,
                "neutral": 207,
                "positive": 11
            }
        }
    ],
    "orderBy": "volume",
    "orderDirection": "desc"
}

X Emoticons

curl -X GET 'https://api.brandwatch.com/projects/397382923/data/emoticons?queryId=1834636622&startDate=2023-11-11&endDate=2023-11-18'

The result will look like the following:

{
    "results": [
        {
          "impressions": 4142732,
          "volume": 469,
          "reachEstimate": 1596865,
          "retweets": 156,
          "tweets": 313,
          "label": "spaghetti",
          "name": "🍝",
          "sentiment": {
              "negative": 0,
              "neutral": 108,
              "positive": 0
          }
        }
    ],
    "orderBy": "volume",
    "orderDirection": "desc"
}

X Stories

curl -X GET https://api.brandwatch.com/projects/397382923/data/urls?queryId=1834636622&startDate=2023-11-11&endDate=2023-11-18

The result will look like the following:

{
    "results": [
        {
          "impressions": 3366927,
          "volume": 48,
          "reachEstimate": 121891,
          "retweets": 46,
          "tweets": 2,
          "label": null,
          "name": "https://www.nytimes.com/2024/05/17/t-magazine/best-pasta-italy.html?smtyp=cur&smid=tw-tmagazine",
          "sentiment": {
              "negative": 0,
              "neutral": 108,
              "positive": 0
          }
        }
    ],
    "orderBy": "volume",
    "orderDirection": "desc"
}

X Mentioned Authors

curl -X GET 'https://api.brandwatch.com/projects/397382923/data/mentionedauthors?queryId=1834636622&startDate=2023-11-11&endDate=2023-11-18'

The result will look like the following:

{
    "results": [
        {
          "impressions": 50330,
          "volume": 106,
          "reachEstimate": 15964,
          "retweets": 106,
          "tweets": 0,
          "label": null,
          "name": "@cbgunionglobal",
          "sentiment": {
              "negative": 0,
              "neutral": 108,
              "positive": 0
          }
        }
    ],
    "orderBy": "volume",
    "orderDirection": "desc"
}