# 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](#tag/Instagram/paths/~1instagram~1search/post) 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](#tag/Instagram/paths/~1instagram~1profile~1{userId}~1report/get) 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. # Pagination 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. ## Servers ``` https://api.modash.io/v1 ``` ## Security ### accessToken Please enter token in following format: Bearer \ Type: http In: header Name: Authorization Scheme: bearer Bearer Format: token ## Download OpenAPI description [Overview](https://docs.modash.io/_bundle/products/discovery_api/openapi_doc/discovery.yaml) ## ### Search by Email - [POST /email-search](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/multiplatformcontroller_emailsearch.md): 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. ## YouTube API for receiving data about YouTube influencers ### Search Influencers - [POST /youtube/search](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/youtube/youtubecontroller_search.md): 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 Audience filters support weights:Expand to see additional informationWeights 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. ### Get Influencer report - [GET /youtube/profile/{userId}/report](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/youtube/youtubecontroller_report.md): Influencer contact details are not enabled by default. Contact us to unlock this data for free. Every successful request costs 1 credit. ### List Languages - [GET /youtube/languages](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/youtube/youtubecontroller_languages.md): Search the list of languages for Influencers. A successful request costs 0 credits. ### List Locations - [GET /youtube/locations](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/youtube/youtubecontroller_locations.md): Search the list of locations for Influencers. A successful request costs 0 credits. ### Audience overlap reports - [POST /youtube/reports/audience/overlap](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/youtube/youtubecontroller_influencersaudienceoverlap.md): Check audience (followers) overlap for several influencers. A successful request costs 1 credit. ### List Users - [GET /youtube/users](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/youtube/youtubecontroller_users.md): Search the list of influencers. A successful request costs 0 credits. ### List Topics - [GET /youtube/topics](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/youtube/youtubecontroller_topics.md): Search for topics. A successful request costs 0 credits. ### List Hashtags - [GET /youtube/hashtags](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/youtube/youtubecontroller_hashtags.md): Search for hashtags. A successful request costs 0 credits. ### Get Influencer Collaborations (deprecated) - [GET /youtube/collaborations/influencer](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/youtube/youtubecontroller_brandtimelineinfluencer.md): 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 This endpoint is deprecated and will be removed in the future. Please use the new, improved and cheaper Collaborations endpoint instead. ## TikTok API for receiving data about TikTok influencers ### Search Influencers - [POST /tiktok/search](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/tiktok/tiktokcontroller_search.md): 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 Audience filters support weights:Expand to see additional informationWeights 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. ### Get Influencer report - [GET /tiktok/profile/{userId}/report](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/tiktok/tiktokcontroller_report.md): Influencer contact details are not enabled by default. Contact us to unlock this data for free. Every successful request costs 1 credit. ### List Languages - [GET /tiktok/languages](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/tiktok/tiktokcontroller_languages.md): Search the list of languages for Influencers. A successful request costs 0 credits. ### List Locations - [GET /tiktok/locations](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/tiktok/tiktokcontroller_locations.md): Search the list of locations for Influencers. A successful request costs 0 credits. ### List Users - [GET /tiktok/users](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/tiktok/tiktokcontroller_users.md): Search the list of influencers. A successful request costs 0 credits. ### List Topics - [GET /tiktok/topics](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/tiktok/tiktokcontroller_topics.md): Search for topics. A successful request costs 0 credits. ### List Hashtags - [GET /tiktok/hashtags](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/tiktok/tiktokcontroller_hashtags.md): Search for hashtags. A successful request costs 0 credits. ### Get Influencer Collaborations (deprecated) - [GET /tiktok/collaborations/influencer](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/tiktok/tiktokcontroller_brandtimelineinfluencer.md): 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 This endpoint is deprecated and will be removed in the future. Please use the new, improved and cheaper Collaborations endpoint instead. ### Get Brand Collaborations (deprecated) - [GET /tiktok/collaborations/brand](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/tiktok/tiktokcontroller_brandtimelinebrand.md): 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 This endpoint is deprecated and will be removed in the future. Please use the new, improved and cheaper Collaborations endpoint instead. ## Instagram API for receiving data about Instagram influencers ### Search Influencers - [POST /instagram/search](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_search.md): 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 Audience filters support weights:Expand to see additional informationWeights 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 interests, 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. ### Get Influencer Report - [GET /instagram/profile/{userId}/report](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_report.md): To protect our enterprise customers, influencer contact details are not enabled by default. Contact us to unlock them for free. Every successful request costs 1 credit. ### Audience overlap reports - [POST /instagram/reports/audience/overlap](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_influencersaudienceoverlap.md): Check audience (followers) overlap for several influencers. A successful request costs 1 credit. ### List Partnerships (brands) - [GET /instagram/brands](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_brands.md): Search the list of Partnerships (brands) that have worked with the influencer. A successful request costs 0 credits. ### List Interests - [GET /instagram/interests](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_interests.md): Search the list of interests. A successful request costs 0 credits. ### List Topics - [GET /instagram/topics](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_topics.md): Search for topics. A successful request costs 0 credits. ### List Languages - [GET /instagram/languages](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_languages.md): Search the list of languages for Influencers. A successful request costs 0 credits. ### List Locations - [GET /instagram/locations](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_locations.md): Search the list of locations for Influencers. A successful request costs 0 credits. ### List Users - [GET /instagram/users](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_users.md): Search the list of influencers. A successful request costs 0 credits. ### List Hashtags - [GET /instagram/hashtags](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_hashtags.md): Search for hashtags. A successful request costs 0 credits. ### Get Influencer Collaborations (deprecated) - [GET /instagram/collaborations/influencer](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_brandtimelineinfluencer.md): 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 This endpoint is deprecated and will be removed in the future. Please use the new, improved and cheaper Collaborations endpoint instead. ### Get Brand Collaborations (deprecated) - [GET /instagram/collaborations/brand](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/instagram/instagramcontroller_brandtimelinebrand.md): 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 This endpoint is deprecated and will be removed in the future. Please use the new, improved and cheaper Collaborations endpoint instead. ## AI Search AI Search allows you to find influencers based on the type of content they create, specifically by analyzing the images and videos that they post. It is a beta feature and is available to all Discovery API users. P.S. it currently only supports Instagram influencers who have greater than 10000 followers. ### Instagram Text-based AI Search - [POST /ai/instagram/text-search](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/ai-search/aisearchcontroller_igtextsearch.md): Search for influencers using a text based query i.e. "woman with curly hair lifting weights" (along with other filters). This API has a fixed 1 RPS limit for searches. Each successful request consumes 0.15 credits. ### Instagram Image-based AI Search - [POST /ai/instagram/image-search](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/ai-search/aisearchcontroller_igimagesearch.md): Search for influencers using an image based query (along with other filters) and you will get influencers who have posted content similar to the query image. This API has a fixed 1 RPS limit for searches. Each successful request consumes 0.15 credits. ### TikTok Text-based AI Search - [POST /ai/tiktok/text-search](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/ai-search/aisearchcontroller_tttextsearch.md): Search for influencers using a text based query i.e. "woman with curly hair lifting weights" (along with other filters). This API has a fixed 1 RPS limit for searches. Each successful request consumes 0.15 credits. ### TikTok Image-based AI Search - [POST /ai/tiktok/image-search](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/ai-search/aisearchcontroller_ttimagesearch.md): Search for influencers using an image based query (along with other filters) and you will get influencers who have posted content similar to the query image. This API has a fixed 1 RPS limit for searches. Each successful request consumes 0.15 credits. ### YouTube Text-based AI Search - [POST /ai/youtube/text-search](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/ai-search/aisearchcontroller_yttextsearch.md): Search for influencers using a text based query i.e. "woman with curly hair lifting weights" (along with other filters). This API has a fixed 1 RPS limit for searches. Each successful request consumes 0.15 credits. ### Brands Dictionary - [GET /ai/brands](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/ai-search/aisearchcontroller_brandsdictionary.md): Get a list of brands that match the search query. Results from this endpoint are only valid for AI Search filters. Just like other dictionary endpoints, this endpoints costs nothing and there are no strict rate limits. ### Instagram Text-based AI Search (deprecated) - [POST /ai/text-search](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/ai-search/aisearchcontroller_textsearch.md): Search for influencers using a text based query i.e. "woman with curly hair lifting weights" (along with other filters). This API has a fixed 1 RPS limit for searches. Each successful request consumes 0.15 credits. ### Instagram Image-based AI Search (deprecated) - [POST /ai/image-search](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/ai-search/aisearchcontroller_imagesearch.md): Search for influencers using an image based query (along with other filters) and you will get influencers who have posted content similar to the query image. This API has a fixed 1 RPS limit for searches. Each successful request consumes 0.15 credits. ## Collaborations These endpoints return posts or summaries for the collaborations between influencers and brands. These APIs can help you monitor partnerships, analyze campaign performance, track competitor activity, and power influencer discovery or reporting tools at scale. ### Get collaboration posts - [POST /collaborations/posts](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/collaborations/collaborationscontroller_posts.md): This endpoint returns collaborated posts where influencers mention brands or vice versa. Every successful request costs 0.2 credit. ### Get collaboration summary - [POST /collaborations/summary](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/collaborations/collaborationscontroller_summary.md): This endpoint aggregates performance data (total as well as per_brand/per_influencer) across the collaborated posts, including total_likes, total_shares, total_views, total_collects, and total_plays. Every successful request costs 0.2 credit. ## User Account API for Modash user account management ### Get User Account Info - [GET /user/info](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/user-account/usercontroller_info.md) ## System System endpoints for service health and monitoring ### Health check - [GET /health](https://docs.modash.io/products/discovery_api/openapi_doc/discovery/system/appcontroller_gethealth.md): The health endpoint provides a real-time status of the API, indicating whether the system is Healthy, Degraded, or Unhealthy based on the performance of recent requests.Note: The service health calculation includes all Discovery endpoints but excludes Raw Data endpoints.