Skip to main content

How Do I Fetch Mentions Using the API?

Updated over a month ago

Fetching mentions is one of the most important things you can do with the BrandMentions API.

To fetch mentions using the BrandMentions API, you have two main approaches:

  1. On the spot searches

    • Create a search job with PostSearch.

    • Retrieve mentions with GetMentions.

    • Optionally use GetProcessedMentions for partial, in progress results.
      ​

  2. Project based searches

    • Use ListProjects to find the project_id.

    • Fetch mentions with GetProjectMentions for that project.

Both methods use the same base URL and rely on your API key for authentication.

To use any of these examples, you need a valid BrandMentions API key issued by the BrandMentions team and included as the api_key parameter in every request.

Two main ways to fetch mentions

You can retrieve mentions from the BrandMentions API in two primary ways:

1. Fetching mentions with on the spot searches

On the spot searches let you run ad hoc searches directly through the API, without creating or editing a project in the BrandMentions web interface.

This is a two step process:

  1. Create a search job with PostSearch.

  2. Retrieve the results with GetMentions (and optionally GetProcessedMentions while it runs).
    ​

Step 1 - Create a search job with PostSearch

You start by calling the PostSearch command and specifying at least one keyword. You can also pass optional parameters such as date range, language, country, and more, depending on your use case.
​

Example:

https://api.brandmentions.com/command.php?api_key=YOUR_API_KEY&command=PostSearch&keyword1=mybrand

In this example:

  • api_key=YOUR_API_KEY
    is your unique API key.

  • command=PostSearch
    tells the API you want to create a new on the spot search job.

  • keyword1=mybrand
    is the first keyword you want to search for.

The PostSearch response will include a search_hash, which is a unique identifier for this search job. You will use that search_hash in the next step.
​

Tip: Store the search_hash safely in your application so you can query for results later or re-run the logic if needed.
​

Step 2 - Retrieve mentions with GetMentions

After the search job has been processed, you can retrieve the full results using the GetMentions command and the search_hash from the previous step.
​

Example:

https://api.brandmentions.com/command.php?api_key=YOUR_API_KEY&command=GetMentions&search_hash=THE_SEARCH_HASH


Replace THE_SEARCH_HASH with the actual value returned by PostSearch.
​

This call returns the complete list of mentions that match your search.
​

Optional - Get partial results with GetProcessedMentions

If you are building something that benefits from real time or near real time updates, you can start reading mentions while the search is still running.
​

Use the GetProcessedMentions command:
​

https://api.brandmentions.com/command.php?api_key=YOUR_API_KEY&command=GetProcessedMentions&search_hash=THE_SEARCH_HASH

This endpoint returns the mentions that have been processed so far, which is useful for:

  • Live dashboards

  • Streaming style monitoring

  • Early alerting while the search continues to run

You can poll this endpoint periodically until all mentions are available, then optionally switch to GetMentions for the final, complete result.

2. Fetching mentions from existing projects

Most ongoing monitoring workflows in BrandMentions are organized into projects. Each project has:

  • A set of keywords and rules

  • Language and location filters

  • Other configuration specific to that brand or topic

If you already have a project in your BrandMentions account, you can fetch its mentions with a single command: GetProjectMentions.

Step 1 - Identify the project

To fetch mentions for a project, you need its project_id.
​

You can get that by calling ListProjects:

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

The response will include a list of projects with their corresponding IDs.
​
Choose the project_id for the project you want to query.
​

Step 2 - Fetch mentions with GetProjectMentions

Once you know the project_id, you can call GetProjectMentions:
​

https://api.brandmentions.com/command.php?api_key=YOUR_API_KEY&command=GetProjectMentions&project_id=THE_PROJECT_ID

Replace THE_PROJECT_ID with the actual ID of your project.
​

This command returns a paginated list of mentions for that project.

Depending on the API parameters supported, you can usually:

  • Filter by date range

  • Apply additional filters (for example type, sentiment, or source, when available)

  • Control pagination (page size and page number or offset)

This method is ideal for:

  • Regular exports of project mentions

  • Feeding data into BI tools or dashboards

  • Keeping an internal database in sync with BrandMentions

Choosing between on the spot and project based searches

Use on the spot searches when you:

  • Want to test or explore a new keyword quickly

  • Need a one time or ad hoc export

  • Do not want to create a permanent project for this use case

Use project based searches when you:

  • Already monitor a brand, client, or topic in a project

  • Need ongoing, repeatable retrieval of mentions

  • Want consistency between what you see in the BrandMentions interface and what you pull via API

In many setups, teams use both:

  • Projects for core brands and clients

  • On the spot searches for campaigns, experiments, or quick checks

Once you integrate these commands into your scripts or applications, you can fully automate how you collect, store, analyze, and visualize your BrandMentions data.

Did this answer your question?