Modash API Best Practices for Developers

General Overview

Modash offers two powerful APIs to help you find, evaluate, and track influencers:

Feature	Discovery API	RAW API
Data Type	Pre-processed influencer data	Real-time, raw social media data
Best For	Search & reports	Campaign tracking & enrichment
Use Cases	Influencer discovery, audience insights	Monitoring posts, audience overlap, comments
Data Limits	1k+ followers (IG/TT/YT), 5k avg views (YT)	No follower thresholds
Pricing	Credit-based per endpoint	Request-based pricing per endpoint

Discovery Thresholds

Modash aims to index and generate reports for:

Instagram & TikTok: Public profiles with 1,000+ followers
YouTube: Creators with 1,000+ followers and 5,000+ average views

⚠️ Note: These thresholds define which accounts are prioritized for inclusion in /search and eligible for report generation.

Profiles below these thresholds may still be added if requested, though coverage and data freshness may vary.

RAW API Note:

No thresholds. Returns public data if the account is accessible.

Getting Started

Authentication

Use your API key from the Modash Developer Portal in the Authorization header:

Authorization: Bearer YOUR_API_KEY

First Call Example

Start by searching for influencers using the Discovery API.

Endpoint: POST /v1/discovery/search

Note: Discovery API requires filters to be passed in the request body as JSON, not as query parameters.

Simple Example Request (cURL)

curl -X POST https://api.modash.io/v1/discovery/search \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "page": 0,
    "sort": {
      "field": "followers",
      "direction": "desc"
    },
    "filter": {
      "influencer": {
        "relevance": ["#topgear"]
      }
    },
    "limit": 15
  }'

⚠️ The /search endpoint does not support URL query parameters.

Add More Filters

Modash supports filters like:

Follower range
Country
Hashtags
Bio keywords
Engagement rate
Audience demographics (gender, language, credibility)
Interests (Instagram only)

Start simple, then layer filters as needed. For full schema, see the Modash API Docs.

API Monitoring & Usage

Health Check

Check if Modash API is online:

GET /health Response: { "status": "ok" }

Safe to ping every 1–5 minutes. Great for internal status pages.

Usage & Quota Tracking

GET /account

Shows remaining Discovery credits
Shows remaining RAW API request
Good for internal dashboards or alerts

🔐 Requires Authorization: Bearer YOUR_API_KEY

What’s Next: Build with Best Practices

Discovery API: Best Practices & Onboarding

Efficient use of /search and profile reports
Pagination & caching to reduce credit cost
Rate limit handling and report refresh logic

Search Optimization Guide

Platform-specific filtering logic
Relevance vs. interests
How to implement Lookalikes
UI best practices for filter UX

RAW API: Best Practices & Onboarding

Real-time post, story, comment, and follower tracking
Retry strategies and rate limit handling
Enrich Discovery results with live data

📩 Need Help?

Email us at hello+api@modash.io or explore full documentation at docs.modash.io