Overview

Discovery API provides powerful products for different use cases. Let us provide a brief overview:

Search allows you to build comprehensive search experience to find creators. Use filters, lookalikes and our dictionaries and lists to create stunning user interfaces.

Reports provide in depth analytics that include audience demographics, performance metrics, sponsored posts and much more.

Our collaborations products enable you to create overviews of past brand partnerships between creators and brands.

There is more: Search by Email allows you to lookup which creator accounts are associated with an emails and audience overlap identifies the uniqueness of an audience with ease.

Testing the API

Search

You can test out the Instagram Search API for free by leaving the filter object empty. Your request body should look similar to this.

> POST https://api.modash.io/v1/instagram/search
{
	"sort": {
		"field": "followers",
		"direction": "desc"
	},
	"filter": {
	}
}

Reports

To test out the Instagram Reports API for free you can set the userId as instagram. Your request should look like this.

> GET https://api.modash.io/v1/instagram/profile/instagram/report

We recommend always using the report route and caching the result if necessary. Everything that is included in the overview is also in a report.

When using the Search API, each response has in total 15 influencers. If you wish to query more influencers for the same query you need to increment the page parameter in the request body.

By default the page parameter is set to 0.

Dictionaries

Interests, Locations and brands

When finding influencers by interests, locations or brands you need to search by their respective ID. To list all interests, locations or brands you need to call the https://api.modash.io/v1/instagram/interests, https://api.modash.io/v1/instagram/locations, https://api.modash.io/v1/instagram/brands route.

You can specify the list of interests, locations or brands returned by using the query parameter and limit the amount of list items returned by using the limit parameter.

By default the limit parameter is set to 20. You can query all list items by setting the limit parameter to 1000000.

Languages

Similar to interests, locations and brands, you first need to find the correct language code to search by. This can be done by calling the https://api.modash.io/v1/instagram/languages route.

Download OpenAPI description

discovery.json

discovery.yaml

Overview

URL

https://www.modash.io

API Support

hello@modash.io

Servers

https://api.modash.io/v1/

Search by Email

Request

For each email provided, identify one or more social media accounts on Instagram, YouTube, or TikTok that have listed this email in their bio or as their contact information.
A successful request costs 0.02 credits per matched email. To execute this request, the account must have a minimum of 0.02 credits multiplied by the number of provided emails, otherwise a not_enough_credits error will be returned.
We do not store the email addresses that you send us.

Security

accessToken

Bodyapplication/jsonrequired

emailsArray of strings[ 1 .. 1000 ] itemsrequired

List of emails to search

curl -i -X POST \
  https://api.modash.io/v1/email-search \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "emails": [
      "string"
    ]
  }'

Responses

Bodyapplication/json

errorboolean

If there is an error

Example: false

matchedEmailsArray of objects(MatchedEmail)

Matches by email

notMatchedEmailsArray of strings

Emails that were not matched

totalMatchesnumberrequired

Number of matched emails

Example: 1

Response

application/json

{
  "error": false,
  "matchedEmails": [
    { … }
  ],
  "notMatchedEmails": [
    "string"
  ],
  "totalMatches": 1
}

YouTube

API for receiving data about YouTube influencers

Operations

TikTok

API for receiving data about TikTok influencers

Operations

Search Influencers

Request

Get a list of influencers that match your filters.
A successful request costs 0.01 credits per search result, with a typical request totaling 0.15 credits for up to 15 results per page

Filtering and adding match data:

Expand to see additional information

When filtering by one or more fields, it is advisable to include these same fields in the sorting process. This ensures that you can retrieve the match information associated with each result. By adding the filtering fields to the sorting criteria, you gain access to detailed match info for every result obtained.

Example: If you want to filter by age you would also sort the results by age:


			{
				
 "sort": { "direction": "desc", "field": "audience_age", "sortedValue": "18-24", "value": "18-24" },
				
 "page": 0,
				
 "filter": { "audience": { "age": [{"id": "18-24", "weight": 0.3}] } }
			
}

You will retrieve match info that will provide details on how well each result matches the filtering criteria. The match info should include two fields:
-code: represents the filtering field that corresponds to the result
-percentage: quantifies the degree of similarity or relevance

Audience filters support weights:

Expand to see additional information

Weights allow you to set a threshold for the chosen filter. If you remove the weight - we will apply the default weight per filter.
Using multiple filters simultaneously results in a logical AND, while applying multiple objects into an array (works with location and age) are applied as a logical OR

Example: If you want at least 30% of the audience to be at the age of 18-24, you can use the weight property of 0.3. We recommend starting with low weight and gradually increasing the percentage. You can find the default thresholds in the notes of each filter.

Expand the filter object below to see all available options.

Security

accessToken

Bodyapplication/jsonrequired

pagenumber[ 0 .. 665 ]

Page number

Default 0

calculationMethodstring

If specified, this indicates the method used to compute average-based metrics, such as average number of likes, comments, shares, etc.

Default "median"

Enum"median""average"

Example: "median"

sortobject

Sorting

filterobject(TikTokSearchFilters)

curl -i -X POST \
  https://api.modash.io/v1/tiktok/search \
  -H 'Authorization: Bearer <YOUR_token_HERE>' \
  -H 'Content-Type: application/json' \
  -d '{
    "page": 0,
    "calculationMethod": "median",
    "sort": {
      "field": "followers",
      "value": 123,
      "direction": "desc"
    },
    "filter": {
      "influencer": {
        "followers": {
          "min": 20000,
          "max": 70000
        },
        "engagementRate": 0.02,
        "location": [
          148838,
          62149,
          80500,
          1428125,
          304716
        ],
        "language": "en",
        "lastposted": 90,
        "relevance": [
          "#cars",
          "@topgear"
        ],
        "audienceRelevance": [
          "@topgear"
        ],
        "gender": "MALE",
        "age": {
          "min": 18,
          "max": 25
        },
        "followersGrowthRate": {
          "interval": "i6months",
          "value": 0.01,
          "operator": "gt"
        },
        "bio": "photos videos",
        "views": {
          "min": 5000,
          "max": 10000
        },
        "hasContactDetails": [
          {
            "contactType": "email",
            "filterAction": "must"
          }
        ],
        "textTags": [
          {
            "type": "hashtag",
            "value": "carsofinstagram"
          },
          {
            "type": "mention",
            "value": "topgear"
          }
        ],
        "keywords": "cars",
        "isVerified": true,
        "likesGrowthRate": {
          "interval": "i1month",
          "value": 0.2,
          "operator": "gt"
        },
        "shares": {
          "min": 5000,
          "max": 10000
        },
        "saves": {
          "min": 5000,
          "max": 10000
        },
        "engagements": {
          "min": 5000,
          "max": 10000
        },
        "filterOperations": [
          {
            "operator": "and",
            "filter": "followers"
          }
        ]
      },
      "audience": {
        "location": [
          {
            "id": 148838,
            "weight": 0.2
          },
          {
            "id": 62149,
            "weight": 0.2
          },
          {
            "id": 80500,
            "weight": 0.2
          },
          {
            "id": 1428125,
            "weight": 0.2
          },
          {
            "id": 304716,
            "weight": 0.2
          }
        ],
        "language": {
          "id": "en",
          "weight": 0.2
        },
        "gender": {
          "id": "MALE",
          "weight": 0.5
        },
        "age": [
          {
            "id": "18-24",
            "weight": 0.3
          },
          {
            "id": "65-",
            "weight": 0.3
          }
        ],
        "ageRange": {
          "min": "18",
          "max": "24",
          "weight": 0.3
        }
      }
    }
  }'

Responses

Bodyapplication/json

errorboolean

If there is an error

Example: false

totalnumberrequired

Number of results

Example: 2

lookalikesArray of objects(InfluencerResponse)required

Lookalikes

lookalikes[].userIdstringrequired

User Id

Example: "173560420"

lookalikes[].profileobjectrequired

Profile info of influencer

lookalikes[].profile.userIdstring

User id of the influencer

Example: "173560420"

lookalikes[].profile.fullnamestring

Full name of Influencer

Example: "Instagram"

lookalikes[].profile.usernamestringrequired

Username of Influencer

Example: "instagram"

lookalikes[].profile.urlstringrequired

Profile URL

Example: "https://www.instagram.com/instagram/"

lookalikes[].profile.picturestringrequired

Profile Picture

Example: "https://imgigp.modash.io/?https://scontent-arn2-1.cdninstagram.com/t51.2885-19/s320x320/22159423_1794482210565499_9190891265074397184_n.jpg"

lookalikes[].profile.followersnumberrequired

Follower count

Example: 313560626

lookalikes[].profile.engagementsnumberrequired

Engagements

Example: 857994

lookalikes[].profile.engagementRatenumberrequired

Engagement rate

Example: 0.0027362938100525414

lookalikes[].matchobject

Sorting match info

directsArray of objects(InfluencerResponse)required

Directs

directs[].userIdstringrequired

User Id

Example: "173560420"

directs[].profileobjectrequired

Profile info of influencer

directs[].profile.userIdstring

User id of the influencer

Example: "173560420"

directs[].profile.fullnamestring

Full name of Influencer

Example: "Instagram"

directs[].profile.usernamestringrequired

Username of Influencer

Example: "instagram"

directs[].profile.urlstringrequired

Profile URL

Example: "https://www.instagram.com/instagram/"

directs[].profile.picturestringrequired

Profile Picture

Example: "https://imgigp.modash.io/?https://scontent-arn2-1.cdninstagram.com/t51.2885-19/s320x320/22159423_1794482210565499_9190891265074397184_n.jpg"

directs[].profile.followersnumberrequired

Follower count

Example: 313560626

directs[].profile.engagementsnumberrequired

Engagements

Example: 857994

directs[].profile.engagementRatenumberrequired

Engagement rate

Example: 0.0027362938100525414

directs[].matchobject

Sorting match info

isExactMatchbooleanrequired

Are the results exactly matching the filters you provided? If we don't find exact results then we try to show similar users by automatically removing some filters for you.

Example: true

Response

application/json

{
  "error": false,
  "total": 2,
  "lookalikes": [
    { … }
  ],
  "directs": [
    { … }
  ],
  "isExactMatch": true
}

Get Influencer report

Request

Influencer contact details are not enabled by default. Contact us to unlock this data for free.
Every successful request costs 1 credit.

Security

accessToken

Path

userIdstringrequired

User's TikTok handle or user ID from TikTok

Query

calculationMethodstring

If specified, this indicates the method used to compute average-based metrics, such as average number of likes, comments, shares, etc.

Default "median"

Enum"median""average"

curl -i -X GET \
  'https://api.modash.io/v1/tiktok/profile/{userId}/report?calculationMethod=median' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

Bodyapplication/json

errorboolean

If there is an error

Example: false

profileobject(TikTokReportProfile)required

profile.userIdstringrequired

User Id

Example: "173560420"

profile.profileobject

Influencer Profile

profile.audienceobject

Audience data

profile.secUidstringrequired

profile.statsByContentTypeobject

User stats separated by content type

profile.recentPostsArray of objects(TikTokRecentPost)

List Languages

Request

Search the list of languages for Influencers.

Security

accessToken

Query

limitnumber

Max items to get

querystring

String to search by

curl -i -X GET \
  'https://api.modash.io/v1/tiktok/languages?limit=0&query=string' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

Bodyapplication/json

errorboolean

If there is an error

Example: false

languagesArray of objects(Language)required

languages[].codestringrequired

Enum"af""als""am""an""ar""arz""as""ast""av""az"

Example: "en"

languages[].namestringrequired

Example: "English"

totalnumberrequired

Total number of languages

Example: 98

Response

application/json

{
  "error": false,
  "languages": [
    { … }
  ],
  "total": 98
}

List Locations

Request

Search the list of locations for Influencers.

Security

accessToken

Query

limitnumber

Max items to get

querystring

String to search by

curl -i -X GET \
  'https://api.modash.io/v1/tiktok/locations?limit=0&query=string' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

Bodyapplication/json

errorboolean

If there is an error

Example: false

locationsArray of objects(Location)required

locations[].idnumberrequired

Id of the location

Example: 51800

locations[].namestringrequired

Name of the location

Example: "London"

locations[].titlestringrequired

Full title of the location

Example: "London, United Kingdom"

totalnumberrequired

Total number of locations

Example: 8477

Response

application/json

{
  "error": false,
  "locations": [
    { … }
  ],
  "total": 8477
}

List Users

Request

Search the list of influencers.

Security

accessToken

Query

limitnumber

Max items to get

querystring

String to search by

curl -i -X GET \
  'https://api.modash.io/v1/tiktok/users?limit=0&query=string' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

Bodyapplication/json

errorboolean

If there is an error

Example: false

usersArray of objects(UserInfluencer)required

users[].userIdstringrequired

User Id

Example: "232192182"

users[].usernamestringrequired

Username

Example: "therock"

users[].fullnamestringrequired

User's full name

Example: "therock"

users[].picturestringrequired

User's profile image URL

Example: "https://imgigp.modash.io/v2?mb0KwpL92uYofJiSjDn1%2F6peL1lBwv3s%2BUvShHERlDbrEEwrWumIvR20xZeZXa0LDeIrcniqZeG9S%2F1a5s2Rx3FZdXrWpY%2BmSBJp1l%2FmBGon3rcHA4EfuatZqMhVBzAT"

users[].followersnumberrequired

User's number of followers

Example: 313583625

users[].isVerifiedbooleanrequired

User has verified badge

Example: true

Response

application/json

{
  "error": false,
  "users": [
    { … }
  ]
}

List Topics

Request

Search for topics

Security

accessToken

Query

limitnumber

Max items to get

querystring

String to search by

curl -i -X GET \
  'https://api.modash.io/v1/tiktok/topics?limit=0&query=string' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

Bodyapplication/json

errorboolean

If there is an error

Example: false

tagsArray of stringsrequired

Response

application/json

{
  "error": false,
  "tags": [
    "string"
  ]
}

List Hashtags

Request

Search for hashtags

Security

accessToken

Query

limitnumber

Max items to get

querystring

String to search by

curl -i -X GET \
  'https://api.modash.io/v1/tiktok/hashtags?limit=0&query=string' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

Bodyapplication/json

errorboolean

If there is an error

Example: false

tagsArray of stringsrequired

Response

application/json

{
  "error": false,
  "tags": [
    "string"
  ]
}

Get Performance Data

Request

Returns the performance data of a TikTok account for the last 6, 12 and 30 posts.
The data is computed on demand, so if it is not available from the first request, a second call should be performed after ~1 minute.
Every successful request costs 0.25 credits. If the response code is retry_later or there is an error on our side you will not be charged.

Security

accessToken

Query

urlstringrequired

Username (@handle) or user id

curl -i -X GET \
  'https://api.modash.io/v1/tiktok/performance-data?url=string' \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

Bodyapplication/json

postsobjectrequired

posts.posts_with_hidden_commentsnumberrequired

posts.totalnumberrequired

posts.likesobjectrequired

posts.likes.meanArray of objectsrequired

posts.likes.mean[].numberOfItemsnumberrequired

posts.likes.mean[].valuenumberrequired

posts.likes.minArray of objectsrequired

posts.likes.min[].numberOfItemsnumberrequired

posts.likes.min[].valuenumberrequired

posts.likes.maxArray of objectsrequired

posts.likes.max[].numberOfItemsnumberrequired

posts.likes.max[].valuenumberrequired

posts.likes.medianArray of objectsrequired

posts.likes.median[].numberOfItemsnumberrequired

posts.likes.median[].valuenumberrequired

posts.commentsobjectrequired

posts.comments.meanArray of objectsrequired

posts.comments.mean[].numberOfItemsnumberrequired

posts.comments.mean[].valuenumberrequired

posts.comments.minArray of objectsrequired

posts.comments.min[].numberOfItemsnumberrequired

posts.comments.min[].valuenumberrequired

posts.comments.maxArray of objectsrequired

posts.comments.max[].numberOfItemsnumberrequired

posts.comments.max[].valuenumberrequired

posts.comments.medianArray of objectsrequired

posts.comments.median[].numberOfItemsnumberrequired

posts.comments.median[].valuenumberrequired

posts.viewsobjectrequired

posts.views.meanArray of objectsrequired

posts.views.mean[].numberOfItemsnumberrequired

posts.views.mean[].valuenumberrequired

posts.views.minArray of objectsrequired

posts.views.min[].numberOfItemsnumberrequired

posts.views.min[].valuenumberrequired

posts.views.maxArray of objectsrequired

posts.views.max[].numberOfItemsnumberrequired

posts.views.max[].valuenumberrequired

posts.views.medianArray of objectsrequired

posts.views.median[].numberOfItemsnumberrequired

posts.views.median[].valuenumberrequired

posts.engagement_rateArray of objectsrequired

posts.engagement_rate[].numberOfItemsnumberrequired

posts.engagement_rate[].valuenumberrequired

posts.posting_statisticsobjectrequired

posts.posting_statistics.weekDayHourobjectrequired

posts.posting_statistics.weekDayHour.meanobjectrequired

posts.posting_statistics.weekDayHour.mean.numberOfItemsnumberrequired

posts.posting_statistics.weekDayHour.mean.valuenumberrequired

posts.posting_statistics.dailyobjectrequired

posts.posting_statistics.daily.meanobjectrequired

posts.posting_statistics.daily.mean.numberOfItemsnumberrequired

posts.posting_statistics.daily.mean.valuenumberrequired

Response

application/json

{
  "posts": {
    "posts_with_hidden_comments": 0,
    "total": 0,
    "likes": { … },
    "comments": { … },
    "views": { … },
    "engagement_rate": [ … ],
    "posting_statistics": { … }
  }
}

Get Influencer CollaborationsDeprecated

Request

Get Brand collaborations for Influencer. This will provide posts for any platform.
A successful request costs 1 credit, for up to 30 results per page

We're currently rebuilding the Collaborations functionality based on user feedback. An improved version is already in development and will soon replace the current implementation. If you're considering using the collaboration endpoints, please contact us for more information.

Security

accessToken

Path

influencerIdstringrequired

Influencer's Tiktok secUid from Tiktok

afterstring

Cursor for pagination

groupedBrandsboolean

Group brands by domain

curl -i -X GET \
  https://api.modash.io/v1/tiktok/collaborations/influencer \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

Bodyapplication/json

errorboolean

If there is an error

Example: false

collaborationsArray of objects(CollaborationsPostInfluencerPaginated)

Collaborations

more_availableboolean

end_cursorstring

Response

application/json

{
  "error": false,
  "collaborations": [
    { … }
  ],
  "more_available": true,
  "end_cursor": "string"
}

Get Brand CollaborationsDeprecated

Request

Get Brand collaborations for Brand. This will provide posts for any platform.
A successful request costs 1 credit, for up to 30 results per page

Security

accessToken

Path

brandIdstringrequired

Brand's Tiktok secUid from Tiktok

afterstring

Cursor for pagination

curl -i -X GET \
  https://api.modash.io/v1/tiktok/collaborations/brand \
  -H 'Authorization: Bearer <YOUR_token_HERE>'

Responses

Bodyapplication/json

errorboolean

If there is an error

Example: false

collaborationsArray of objects(CollaborationsPostInfluencerPaginated)

Collaborations

more_availableboolean

end_cursorstring

Response

application/json

{
  "error": false,
  "collaborations": [
    { … }
  ],
  "more_available": true,
  "end_cursor": "string"
}

Instagram

API for receiving data about Instagram influencers

Operations

User Account

API for Modash user account management

Operations

System

System endpoints for service health and monitoring

Operations

Overview

Testing the API

Search

Reports

Pagination

Dictionaries

Interests, Locations and brands

Languages

Search by Email

Request

Responses

YouTube

TikTok

Search Influencers

RequestExpand all

Responses

Get Influencer report

Request

Responses

List Languages

Request

Responses

List Locations

Request

Responses

List Users

Request

Responses

List Topics

Request

Responses

List Hashtags

Request

Responses

Get Performance Data

Request

Responses

Get Influencer CollaborationsDeprecated

Request

Responses

Get Brand CollaborationsDeprecated

Request

Responses

Instagram

User Account

System

Request