Discovery API: Best Practices & Onboarding (For Developers)

How Discovery API Works

The Discovery API allows you to:

Search for influencers via /search
Fetch detailed data reports via /profile/:userId/report
Evaluate performance metrics via /performance (e.g. average likes, followers, engagement rate)

Typical Integration Flow

Run a search
Select influencers
Fetch report data
(Optional) Fetch performance indicators
Cache results locally (recommended: 30 days)

Search Optimization

Filter Logic

All filters use AND logic between filters
Within filters, the default is OR, however some filters allow the operation logic to be changed also to AND or NOT
Start broad → narrow down as needed
Common filters include: platform, country, follower range, engagement rate, gender, keywords, interests

Keyword & Relevance Filters

bio and keywords use exact match logic (e.g., “vegan” ≠ “veganfood”)
keywords searches only caption text (not hashtags); only one string is supported
relevance filters (topics, lookalikes) use semantic vector search, not keyword matching
To apply semantic sorting, use sort: relevance

Filter Weighting Tip Audience filters (age, gender, interests, language, location) are weighted by default:

Gender: 50%
Age & interests: 30%
Location & language: 20%

You can override weights via the API if needed.

Sorting

Default: followers descending
Supported: followers, engagementRate, engagements, relevance
🔸 Advanced Sort Tip: Some fields (e.g. audienceGeo, audienceInterest) require a matching filter + value to work properly
→ Example: sort: { field: 'audienceGeo', value: '62273' }

UI Optimization (Save Credits)

Best Practices

Wait for users to type at least 4 characters before sending a request
Add 500ms debounce to reduce noisy requests
Cache repeated usernames
Paginate result sets to stay efficient

```javascript
let timeout;

document.getElementById('searchInput').addEventListener('input', function(event) {
  clearTimeout(timeout);
  const query = event.target.value;

  if (query.length >= 4) {
    timeout = setTimeout(() => {
      fetchInfluencerSearch(query);
    }, 500);
  }
});
```

Credit Usage

Discovery API Credit Costs

/search (15 profiles): 0.15 credits
/profile/:userId/report: 1 credit
/performance: 0.25 credits

Caching & Refresh Logic

Modash data is updated on a rolling basis depending on the profile’s popularity and the type of data:

Very basic data (followers, username): refreshed weekly, or when a profile is viewed
Basic data (bio, engagements): refreshed bi-weekly
Analyzed data (audience demographics, performance): refreshed every 30 days

For less popular profiles, updates happen on-demand when fetched via the API or searched on Modash platform.

👉 This means some values (e.g. engagement rate) may appear outdated compared to others (e.g. follower count), which are refreshed more frequently.

To optimize credit use, we recommend caching reports for at least 30 days on your side.

⚠️ Note: The /list-users endpoint is refreshed less frequently than /profile/report. If a profile has just crossed 1,000 followers, it may show up in /search within the next 2–4 weeks. If not yet available, searching for the handle directly can trigger data collection.

Troubleshooting & Edge Cases

Empty Audience Data?

Check report_status
If status is processing, Modash is collecting the data

429 Rate Limit Errors? Use exponential backoff:

const makeRequest = async (url) => {
  try {
    const response = await fetch(url);
    return response;
  } catch (error) {
    if (error.status === 429) {
      const waitTime = Math.random() * 1000 + 1000;
      await new Promise(resolve => setTimeout(resolve, waitTime));
      return await makeRequest(url);
    } else {
      throw error;
    }
  }
};

Profile Not Found in Search?

Platform-specific thresholds apply:
- Instagram & TikTok: 1,000+ followers
- YouTube: 1,000+ followers and 5,000+ average views
Trigger indexing manually with:

GET /profile/:platform/:username

Modash will begin collecting the data if the profile qualifies. The report will be available within 48 hours.

Audience Overlap (Optional)

You can compare audience fields like age, gender, and location across multiple reports.

For true follower-level overlap, use the RAW API instead.

Building a Great Search UX

To replicate Modash’s platform search:

Start with filters like platform, country, and follower range
Reveal advanced filters (hashtags, lookalikes, interests) after basic filters are selected
Use lookalikes to expand results beyond niche filters
Prevent dead-ends with fallbacks:
- Clear filters if no results
- Suggest wider ranges or related topics

For detailed techniques, check the Discovery API Search Optimization Guide.