A quick reference for key concepts, limits, and data points in the Modash API. Keep this handy while building your integration.
This cheat sheet covers the most commonly referenced information across both the Discovery API and RAW API.
Making your first authenticated request
Here's a simple example to verify your authentication is working:
curl -i -X GET <https://api.modash.io/v1/user/info> \\ -H "Authorization: Bearer YOUR_API_KEY"
This calls the /user/info endpoint and returns your account details, including remaining credits and request quotas.
Understanding rate limits
Different endpoints have different rate limits:
Not rate limited: Dictionary endpoints like languages, locations, and interests
Tier-based limits (~2 requests per second): Profile reports, Discovery search, audience overlap
Higher fixed limits (~10 requests per second): Some listing endpoints like topics or hashtags
Rate limiting errors return HTTP status code 429. Always read the HTTP status code and handle rate limit errors separately from other errors.
Handling rate limits
When you hit a rate limit, implement exponential backoff:
Wait 1 second before retrying.
If the retry also fails, wait 2 seconds.
Double the wait time with each consecutive failure.
Set a maximum number of retries (for example, 5 attempts).
š” Build monitoring into your integration early. Use the /account endpoint to track your remaining credits (Discovery) and request quota (RAW API) so you're alerted before hitting limits.
Monitoring your usage
Use the /account endpoint to check:
Remaining Discovery API credits
Remaining RAW API requests
Current plan details
Use the /health endpoint to check API availability. You can safely poll this every few minutes for internal status dashboards.
GET /health { "status": "ok" }
Billing for failed requests
If you receive a failed response (for example, HTTP status code 500), you won't be charged any credits or consume any quota. Failed requests are considered non-billable events.
For full API documentation, visit docs.modash.io. If you need help, email hello+api@modash.io.
Data refresh rates
Profile data refreshes at different cadences:
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
Profile reports: every 2-4 weeks
Search indices: approximately once per month
Popular profiles refresh more often than less frequently analysed accounts. If you need the freshest data, always fetch a report and consider supplementing with the RAW API.
Each profile runs on its own individual cycle, so refreshes can occur at any time during the timeframes mentioned above.
Extra freshness notes
Modash maintains freshness across 350M+ creator profiles, and each profile runs on its own individual refresh cycle.
Some updates may also be triggered when a profile is viewed, so high-traffic profiles can refresh faster than long-tail accounts even within the same general cadence.
Search filters: influencer
Key influencer-level filters include:
Account type: regular, business, or creator
Bio: exact word matches across bio, username, and handle
Brands: creators with sponsored posts mentioning specific brands
Engagement rate: based on likes vs views or followers, depending on platform
Followers and follower growth
Keywords: phrases in post captions or spoken content (for YouTube)
Topics and lookalikes: for relevance and similarity search
TextTags: hashtags and @mentions used in captions
Search filters: audience
You can filter by audience demographics including:
Age, gender, interests, language, and location
Filters can be weighted (default weights favour gender more heavily)
Combine audience filters thoughtfully to avoid over-filtering
Engagement calculations
TikTok and YouTube: average likes divided by average views
Instagram: median likes divided by followers
Calculations typically consider the last ~2 months of content, up to around 500 posts
Paid post performance (PPP) compares engagement on sponsored content vs organic content. A score of 100% means sponsored posts perform the same as organic.
Credibility score
The credibility score estimates what portion of followers appear to be real people.
A score of 0.8 suggests roughly 80% real followers and 20% likely fake. Modash analyses profile pictures, bios, follower/following ratios, activity patterns, and other signals.
Benchmark: The general benchmark for credibility is 0.75 (75% real followers). Creators scoring below this threshold may have a higher-than-typical proportion of fake or inactive followers. Use this as a baseline when evaluating influencer quality, but keep in mind that benchmarks can vary by follower count - a credibility score that looks decent on the surface might actually fall below the median for creators in a similar size range.
Audience lookalikes vs influencer lookalikes
Influencer lookalikes: creators with similar topics and content patterns
Audience lookalikes: accounts with similar follower demographics (based on who follows the account, not on creator content)
š” Use audience lookalikes to expand your discovery beyond obvious choices. If your target influencer reaches "young people in California", audience lookalikes will surface creators with a similar demographic.
Location data
Influencer and audience locations are inferred from location tags, languages, captions, and bios. Modash normalises and maps locations to consistent IDs.
For example - If user wants to filter for Canada, the associated Location ID is 1428125
Fetch the full list of supported locations using the locations dictionary endpoints.
Unified response fields
The creator_description and creator_highlight fields are now available for both Instagram and YouTube profiles. The legacy channel_highlight field remains available for backwards compatibility during the transition.
For full API documentation, visit docs.modash.io. If you need help, email hello+api@modash.io.
FAQs
FAQs
Where do I find my API key?
You can get your API key from the Modash Developer Portal. If you don't see the developer section, check with your team owner about API access.
Can I have multiple API keys?
Contact Modash support at hello+api@modash.io to discuss multiple API keys for your integration.
What happens if I exceed rate limits repeatedly?
You'll continue to receive
429errors. Implement exponential backoff to handle these gracefully. If you consistently need higher limits, contact Modash to discuss your needs.Are rate limits per key or per account?
Rate limits are applied per account. All API keys associated with the same account share the same rate limits.
Do failed requests count against my quota?
No. Requests that return HTTP
500(Internal Server Error) or other server-side failures are not billed.What does a credibility score of 0.6 mean?
It suggests roughly 60% of the account's followers appear to be real people. The remaining 40% may be inactive, fake, or bot accounts.
Can I get more than 20 audience lookalikes?
No. You can get up to 20 lookalikes per profile, sorted by similarity with the most relevant matches first.
How is engagement rate different across platforms?
For TikTok and YouTube, engagement rate is average likes divided by average views. For Instagram, it's median likes divided by followers. This reflects how users interact with content differently on each platform.