When you build real time or time sensitive workflows on top of the BrandMentions API, it helps to know how fresh the data is and how it compares to what you see in the web app.
This guide explains:
How often data is updated in the API versus the app
How callbacks (webhook style notifications) affect freshness
How polling and historical jobs change the timing
Data update frequency: API vs app interface
In normal operation, the API and the web interface use the same data pipeline.
That means:
When a new mention is found and processed, it is made available to:
The BrandMentions web interface
The BrandMentions API
in essentially the same time frame. There is no separate, slower refresh cycle for the API.
Data access method | Data freshness | Notes |
Web interface | Near real time | Uses the same backend as the API |
API with callbacks (webhook style) | Near real time, recommended for freshest data | API notifies you as soon as jobs complete |
API with polling | Depends on your polling interval | Around 13 seconds is a good balance for processed mentions |
Historical data via | Not real time | Data is available after the historical job finishes |
In practical terms:
If you see a mention in the app, it is available through the API as well
If your API based dashboard is pulling data regularly, it can stay in sync with what users see in the app
Real time data with callbacks (webhook style)
For the freshest possible data in your own systems, the best option is to use the API callback functionality, which behaves like webhooks.
How callbacks work
When you create a project or an on the spot search, you can provide a callback URL:
The callback URL is an endpoint on your server
When the job finishes processing (and in some cases as data becomes available), the API sends an HTTP request to that URL
Your system can then immediately call the relevant endpoints, such as
GetMentionsorGetProjectMentions
This gives you:
Near real time notifications as soon as mentions are ready
A delay typically limited to the processing time plus network latency
No need for constant polling from your side
Why callbacks give the freshest data
With callbacks:
You only act when there is something new to fetch
Your integration reacts almost immediately after the BrandMentions system finishes processing mentions
Polling the API for new data
If you cannot use callbacks or webhooks, you can still build near real time workflows by polling the API.
Typical options:
GetMentionsfor on the spot searchesGetProjectMentionsfor project based mentionsGetProcessedMentionsfor partial results as a spot search job runs
Recommended polling interval
For GetProcessedMentions, the documentation recommends a polling interval of about 13 seconds. This is a good general guideline:
Short enough to keep data reasonably fresh
Long enough to avoid unnecessary load and reduce the risk of hitting usage limits
For other endpoints, you can:
Use a similar interval for time sensitive dashboards
Use longer intervals for non critical reports or batch processes
The actual freshness when polling depends entirely on how often your script runs:
Poll every few seconds for near real time views
Poll every few minutes or hours for regular reporting and summaries
Historical data timing
Historical data behaves differently.
When you run a historical job using RunProjectHistorical:
The search is resource intensive and does not finish instantly
The API processes historical mentions for the requested period
Data only becomes available after the job finishes
The usual pattern is:
Trigger
RunProjectHistoricalProvide a callback URL so you know when it completes
After the callback, use endpoints like
GetProjectMentionsto retrieve the backfilled data
This means:
Historical data is not real time
You should design your workflow so it waits for completion before reading data
By choosing the right combination of callbacks and polling, and by understanding how historical processing works, you can design API based dashboards and workflows that match the freshness and reliability of the BrandMentions web interface.