Skip to main content

How Can I Access Analytics or Influencer Data Through the API?

Updated over a month ago

The BrandMentions API does more than return raw mentions. It also gives you access to influencer data and high level analytics that you can plug directly into your own dashboards, reports, and AI workflows.

Which endpoint should I use?

Here is a quick decision guide:

  • Use GetProjectInfluencers if you want top influencers and their metrics for a project.
    ​

  • Use GetMentionsCount if you need a single total mentions number per project.
    ​

  • Use GetRemainingCredits and GetMainKeywordsCount for usage, limits, and planning analytics.
    ​

  • Use GetProjectMentions or GetMentions if you want to build custom analytics, dashboards, or AI features from raw data.


2. Accessing high level analytics with GetMentionsCount and credits endpoints

2.1. Total mentions per project with GetMentionsCount

If you only need how many mentions a project has, not the full list, use the GetMentionsCount command.
​

This endpoint returns a single number:

  • mentions_count – the total number of mentions stored for that project

Parameters

  • project_id (mandatory) – the project you want to count mentions for

Example request

https://api.brandmentions.com/command.php?api_key=YOUR_API_KEY   &command=GetMentionsCount   &project_id=1

Example response:

{   "status": "success",   "mentions_count": 3 }

You can call this regularly (for example daily) and store the values to build:

  • Mention volume trends over time

  • Simple KPIs such as total mentions per campaign or client

Note: GetMentionsCount works at project level and does not accept time, language, or country filters. For filtered counts, fetch mentions with GetProjectMentions and aggregate them yourself (see section 3).

2.2. Monitoring credits and capacity with GetRemainingCredits

For usage and capacity analytics, there is also GetRemainingCredits. It tells you how many credits are left in the account:

  • PostSearch – searches left in the current billing period

  • AddProject – projects you can still create

  • Mentions – historical mentions you can still store

Example:

https://api.brandmentions.com/command.php?api_key=YOUR_API_KEY   &command=GetRemainingCredits

You can display this in internal admin dashboards to avoid hitting limits unexpectedly.

2.3. Estimating keyword usage with GetMainKeywordsCount (boolean projects)

If you use boolean expressions when setting up projects, you can call GetMainKeywordsCount to see how many keyword credits that expression will consume.

  • boolean_expression (mandatory) – URL encoded boolean expression

Example:

https://api.brandmentions.com/command.php?api_key=YOUR_API_KEY   &command=GetMainKeywordsCount   &boolean_expression=brand%20OR%20mentions

Response:

{   "status": "success",   "keywords_count": 2 }

This is useful for planning and budgeting around complex tracking setups.

3. Building custom analytics from raw mentions

For anything beyond simple counts and influencer lists, you can compute your own analytics using the full mentions data returned by:

  • GetProjectMentions – mentions stored for a project

3.1. Fetching project mentions with GetProjectMentions

GetProjectMentions returns mentions in a paginated way and lets you filter by time, source, link status, and country.
​

Key parameters:

  • project_id (mandatory)

  • page and per_page (pagination, default page=1, per_page=100, max 100)

  • start_period and end_period (optional time window)

  • sources[] (web and social sources)

  • linked (linked or unlinked mentions)

  • countries[] (specific country codes or ALL)

Example:

https://api.brandmentions.com/command.php?api_key=YOUR_API_KEY   &command=GetProjectMentions   &project_id=1   &start_period=2019-03-15 15:37:22   &end_period=2019-04-15 16:43:17   &sources[]=web   &sources[]=twitter   &linked=0   &countries[]=ALL

Each mention contains fields like:

  • published, url, title, image_url

  • performance, domain_influence

  • language, country

  • social_network

  • text and sentiment

  • Optional author object for social mentions, with username, name, reach, followers, following

3.2. Example analytics you can compute

Once you have the raw mentions in your own environment, you can build almost any metric you want, such as:

  • Sentiment trends
    Group mentions by date and aggregate by sentiment to see positive vs negative evolution.
    ​

  • Top sources and channels
    Count mentions by social_network or by domain in the url field to find which channels drive the most buzz.
    ​

  • Geographic distribution
    Group by country to identify where your brand is most discussed.
    ​

  • Domain and author influence
    Use domain_influence, author.reach, and author.followers to focus on high impact mentions.

This approach is ideal if you want full control over your analytics and visualizations.

4. Near real time analytics with callbacks and live processing

If you want analytics that update quickly when new data is available, you can combine:

  • Callbacks for search jobs and projects

  • Processed mentions for in progress searches

4.1. Using callback with PostSearch

When you run an on the spot search with PostSearch, you can provide a callback URL. Once the search finishes, BrandMentions will send a POST request to that URL with search_hash in the payload.

Example PostSearch call:
​

https://api.brandmentions.com/command.php?api_key=YOUR_API_KEY   &command=PostSearch   &keyword1=brandmentions   &time_range=day   &languages[]=en   &callback=https://yourapp.com/brandmentions-callback

Your callback handler can then:

  1. Read the search_hash from the incoming request.

  2. Call GetMentions or GetProcessedMentions.

  3. Update your dashboards, aggregates, or AI indexes.

Note: The callback is triggered when the search job is done, not per individual mention.

4.2. Polling GetProcessedMentions for live updates

For near real time analytics on a running search, use GetProcessedMentions with the search_hash. It returns the mentions found so far and a processing_ended flag.

The documentation recommends polling roughly every 13 seconds and stopping when processing_ended becomes true.
​

This is useful for:

  • Monitoring live campaigns

  • Detecting spikes or crises quickly

  • Updating live TV or command center dashboards

4.3. Using callback with AddProject

When you create a project with AddProject, you can also set a callback URL. After the project execution is finished, BrandMentions will call that URL with the project_id.

You can then:

  • Call GetProjectMentions, GetProjectInfluencers, and GetMentionsCount

  • Recompute your analytics is one go

  • Refresh client reports or internal dashboards on every new project run

By combining these endpoints, you can move far beyond basic mention tracking and build a complete analytics and influencer intelligence layer on top of the BrandMentions API.

Did this answer your question?