This guide covers how to authenticate with the Modash API and manage rate limits. Getting authentication right and handling rate limits properly are essential for a reliable integration.
You'll set up authentication once when you start building, and handle rate limits as an ongoing part of your API integration.
Getting your API key
All Modash API requests require authentication. You can get your access token from the Modash Developer Portal.
Use your access token in one of three ways:
Authorization header (recommended):
Authorization: Bearer YOUR_API_KEYBody parameter:
access_tokenin the request bodyQuery parameter:
access_tokenas a query parameter
Keep your API key secure and never expose it in client-side code or public repositories.
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.
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.