Ready to integrate the Modash Discovery API? This guide walks you through the core workflow, helps you optimise credit usage, and gets you up to speed fast - whether you're running a proof-of-concept or going to production.
The Discovery API provides pre-processed influencer and audience data for Instagram, TikTok, and YouTube. It's built for search, discovery, and reporting use cases.
How the Discovery API works
The Discovery API allows you to:
Search for influencers via
/searchFetch detailed data reports via
/profile/:userId/reportEvaluate performance metrics via
/performance(average likes, followers, engagement rate)
A typical integration flow looks like this:
Run a search with your filters.
Select influencers from the results.
Fetch report data for selected profiles.
Optionally fetch performance indicators.
Cache results locally (recommended: 30 days).
Profile reports and data refresh
Profile reports are the richest data source in the Discovery API. Reports include audience demographics, engagement metrics, content analysis, and more.
Key Modash refresh rates:
Very basic data (followers, name, username): at least weekly
Basic data (recent posts, engagement): roughly twice per month
Analysed data (audience, detailed metrics): about once per month
Individual profile reports: every 2-4 weeks
Popular profiles refresh more frequently than long-tail accounts.
💡 Cache Discovery API reports for at least 30 days on your side. This reduces credit consumption and gives you faster response times.
Credit usage and optimisation
Discovery API uses a credit-based pricing model. Different endpoints consume different amounts of credits.
To optimise your credit usage:
Always use pagination (
pageandlimitparameters).Let the backend handle sorting (by followers, engagement, or other fields).
Cache frequently-used searches client-side or in your backend.
Avoid very short queries (1-2 characters produce unreliable results).
Start broad with a few filters, then narrow down over time.
Inclusion thresholds
The Discovery API indexes public profiles that meet minimum thresholds:
Instagram and TikTok: ~1,000+ followers
YouTube: ~1,000+ followers and 5,000+ average views
If a profile is missing, searching for the handle directly can trigger data collection. The profile should appear within 2-4 weeks.
Troubleshooting common issues
If you get empty audience data, check the report_status field. If the status is processing, Modash is still collecting the data.
If you receive 429 rate limit errors, implement exponential backoff:
Wait a short time before retrying.
Double the wait time with each consecutive failure.
Set a maximum retry limit.
For full API documentation and endpoint details, visit docs.modash.io. If you need help, email hello+api@modash.io.
FAQs
FAQs
How many credits does a search request cost?
A search request costs a small number of credits per influencer returned (for example, 0.01 credits per result). Check the API documentation for specific credit costs per endpoint.
Can I test the Discovery API for free?
Yes. You can test the search endpoint by leaving the filter object empty. This lets you verify connectivity and understand the response structure before using credits on filtered searches.
How long until a new profile appears in search results?
When a creator reaches 1,000 followers, they should appear within the next 2-4 weeks. Searching for the handle directly can speed up data collection.
What's the difference between
/searchand/profile/report?/searchreturns a list of influencers matching your filters with basic data./profile/reportreturns a full detailed report for a specific influencer, including audience demographics and detailed analytics.How do I handle profiles with
processingstatus?If
report_statusisprocessing, Modash is collecting the data. Wait and retry after a few hours. The report will typically be available within 48 hours.