{"openapi":"3.1.0","info":{"title":"Enrichment API","version":"1","description":"Email addresses and profile facts for Instagram, TikTok and YouTube creators, one synchronous request at a time, paid in credits only for what it delivers."},"externalDocs":{"url":"https://enrichment.socialgems.io/","description":"The docs, with a console to try each call."},"servers":[{"url":"https://enrichment.socialgems.io"}],"components":{"securitySchemes":{"apiKey":{"type":"http","scheme":"bearer","description":"An API key from https://enrichment.socialgems.io/account."}},"schemas":{"EnrichRequest":{"type":"object","properties":{"handle":{"type":"string","minLength":1,"maxLength":200,"description":"The creator's handle, with or without the @. On YouTube, a channel URL such as https://www.youtube.com/@name also works."},"platform":{"default":"instagram","description":"Where the handle lives. Defaults to instagram.","type":"string","enum":["instagram","tiktok","youtube"]}},"required":["handle"]},"CreatorRequest":{"type":"object","properties":{"handle":{"description":"The creator's handle, with or without the @, or their profile URL. Send this or `id`.","type":"string","minLength":1,"maxLength":200},"platform":{"description":"Where `handle` lives: `instagram` (the default), `tiktok` or `youtube`. A profile URL says it already.","type":"string","enum":["instagram","tiktok","youtube"]},"id":{"description":"A creator `id` from an earlier answer, a merged creator's old one included. Send this or `handle`.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"include":{"default":[],"description":"Modules to add to the profile, each at its own price: `analysis`, `contact`, `partnerships`, `lookalikes`. Leave it out for the profile alone.","type":"array","items":{"type":"string","enum":["analysis","contact","partnerships","lookalikes"]}},"onlyIfFound":{"default":false,"description":"Answer and charge only when the modules asked for come back with a result: each one added to the profile, or the profile when nothing is added. Otherwise the call answers 404 with the missing modules in `details.missing` and charges nothing, the profile included, or 503 when a source failed, which a retry can fix.","type":"boolean"},"fresh":{"default":false,"description":"Read the account again now and redo each module asked for, instead of answering from what we found before. Charges again, an email already unlocked included.","type":"boolean"},"quote":{"default":false,"description":"Price the request without running it or charging.","type":"boolean"}},"additionalProperties":false},"CreatorModuleRequest":{"type":"object","properties":{"handle":{"description":"The creator's handle, with or without the @, or their profile URL. Send this or `id`.","type":"string","minLength":1,"maxLength":200},"platform":{"description":"Where `handle` lives: `instagram` (the default), `tiktok` or `youtube`. A profile URL says it already.","type":"string","enum":["instagram","tiktok","youtube"]},"id":{"description":"A creator `id` from an earlier answer, a merged creator's old one included. Send this or `handle`.","type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},"onlyIfFound":{"default":false,"description":"Answer and charge only when the modules asked for come back with a result: each one added to the profile, or the profile when nothing is added. Otherwise the call answers 404 with the missing modules in `details.missing` and charges nothing, the profile included, or 503 when a source failed, which a retry can fix.","type":"boolean"},"fresh":{"default":false,"description":"Read the account again now and redo each module asked for, instead of answering from what we found before. Charges again, an email already unlocked included.","type":"boolean"},"quote":{"default":false,"description":"Price the request without running it or charging.","type":"boolean"}},"additionalProperties":false},"LookalikesRequest":{"type":"object","properties":{"seeds":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"description":"1 to 10 Instagram creators, by handle (with or without the @) or profile URL. What several seeds share counts more, so each seed added makes the list more specific."},"filters":{"type":"object","properties":{"country":{"description":"Where the creator lives, as ISO 3166 alpha-2 codes, such as `[\"US\"]`.","minItems":1,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"language":{"description":"The language the creator posts in, as ISO 639-1 codes, such as `[\"en\"]`.","minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-z]{2}$"}},"followers":{"description":"A follower range, either end optional.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false},"engagementMin":{"description":"The lowest engagement rate, in percent.","type":"number","minimum":0},"accountType":{"description":"The account types to return. Leaving it out returns people who make content: `real_creator`, `ugc_creator`, `expert`, `business_founder`, `artist`.","minItems":1,"type":"array","items":{"type":"string","enum":["real_creator","ugc_creator","expert","business_founder","brand_or_shop","meme_page","artist","media"]}},"gender":{"description":"Who the main person behind the account is: `woman`, `man`, `couple_or_family`. Pages with no main person are left out.","minItems":1,"type":"array","items":{"type":"string","enum":["woman","man","couple_or_family"]}},"ageBand":{"description":"How old the main person behind the account seems, by band: `18_24`, `25_34`, `35_44`, `45_54`, `55_plus`. Pages with no main person are left out.","minItems":1,"type":"array","items":{"type":"string","enum":["18_24","25_34","35_44","45_54","55_plus"]}},"graphicShareMax":{"description":"The highest share of the latest posts that are text graphics, illustrations or memes, from 0 to 1, such as `0.5`.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false,"description":"Creators outside these are left out. Every filter is optional."},"limit":{"default":25,"description":"How many creators to return, up to 50.","type":"integer","minimum":1,"maximum":50},"quote":{"default":false,"description":"Price the request without running it or charging. A quote prices `limit` creators.","type":"boolean"}},"required":["seeds"],"additionalProperties":false},"FindRequest":{"type":"object","properties":{"prompt":{"description":"The creators you want, in plain words, up to 1,000 characters, such as \"Moms who post about getting organized, planners and productivity. Not accounts that sell their own planners.\" Starts a new search. We judge each creator's recent posts against it, and the bio when the prompt says who to leave out. Hard limits such as country, size or gender go in `filters`.","type":"string","minLength":1,"maxLength":1000},"seeds":{"description":"Sent with a prompt, 1 to 10 Instagram creators like the ones you want, by handle or profile URL. The search keeps them, and they'll shape it once likeness ships. For now they don't change the results.","minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"filters":{"description":"Sent with a prompt. Creators outside these never come back. Only creators with 1,500 followers or more and engagement above zero do, unless `followers` asks for smaller, and never an account under 18. Without `accountType`, only people who make content.","type":"object","properties":{"country":{"description":"Where the creator lives, as ISO 3166 alpha-2 codes, such as `[\"US\"]`.","minItems":1,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"language":{"description":"The language the creator posts in, as ISO 639-1 codes, such as `[\"en\"]`.","minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-z]{2}$"}},"followers":{"description":"A follower range, either end optional.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false},"engagementMin":{"description":"The lowest engagement rate, in percent.","type":"number","minimum":0},"accountType":{"description":"The account types to return. Leaving it out returns people who make content: `real_creator`, `ugc_creator`, `expert`, `business_founder`, `artist`.","minItems":1,"type":"array","items":{"type":"string","enum":["real_creator","ugc_creator","expert","business_founder","brand_or_shop","meme_page","artist","media"]}},"gender":{"description":"Who the main person behind the account is: `woman`, `man`, `couple_or_family`. Pages with no main person are left out.","minItems":1,"type":"array","items":{"type":"string","enum":["woman","man","couple_or_family"]}},"ageBand":{"description":"How old the main person behind the account seems, by band: `18_24`, `25_34`, `35_44`, `45_54`, `55_plus`. Pages with no main person are left out.","minItems":1,"type":"array","items":{"type":"string","enum":["18_24","25_34","35_44","45_54","55_plus"]}},"graphicShareMax":{"description":"The highest share of the latest posts that are text graphics, illustrations or memes, from 0 to 1, such as `0.5`.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false},"exclude":{"description":"Sent with a prompt, up to 5,000 Instagram creators you already have, by handle or profile URL. The search never judges, reads or returns them, so they cost nothing.","minItems":1,"maxItems":5000,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"cursor":{"description":"The last answer's `next.cursor`, sent alone, to continue its search. Sending one again replays its answer for free.","type":"string","minLength":1,"maxLength":100},"quote":{"default":false,"description":"Price the call without running it.","type":"boolean"}},"additionalProperties":false,"description":"A new search sends `prompt`, with `seeds`, `filters` and `exclude` if it has them. Every later call sends only `cursor`."},"FindToolRequest":{"type":"object","properties":{"prompt":{"description":"The creators you want, in plain words, up to 1,000 characters, such as \"Moms who post about getting organized, planners and productivity. Not accounts that sell their own planners.\" Starts a new search. We judge each creator's recent posts against it, and the bio when the prompt says who to leave out. Hard limits such as country, size or gender go in `filters`.","type":"string","minLength":1,"maxLength":1000},"seeds":{"description":"Sent with a prompt, 1 to 10 Instagram creators like the ones you want, by handle or profile URL. The search keeps them, and they'll shape it once likeness ships. For now they don't change the results.","minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"filters":{"description":"Sent with a prompt. Creators outside these never come back. Only creators with 1,500 followers or more and engagement above zero do, unless `followers` asks for smaller, and never an account under 18. Without `accountType`, only people who make content.","type":"object","properties":{"country":{"description":"Where the creator lives, as ISO 3166 alpha-2 codes, such as `[\"US\"]`.","minItems":1,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"language":{"description":"The language the creator posts in, as ISO 639-1 codes, such as `[\"en\"]`.","minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-z]{2}$"}},"followers":{"description":"A follower range, either end optional.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false},"engagementMin":{"description":"The lowest engagement rate, in percent.","type":"number","minimum":0},"accountType":{"description":"The account types to return. Leaving it out returns people who make content: `real_creator`, `ugc_creator`, `expert`, `business_founder`, `artist`.","minItems":1,"type":"array","items":{"type":"string","enum":["real_creator","ugc_creator","expert","business_founder","brand_or_shop","meme_page","artist","media"]}},"gender":{"description":"Who the main person behind the account is: `woman`, `man`, `couple_or_family`. Pages with no main person are left out.","minItems":1,"type":"array","items":{"type":"string","enum":["woman","man","couple_or_family"]}},"ageBand":{"description":"How old the main person behind the account seems, by band: `18_24`, `25_34`, `35_44`, `45_54`, `55_plus`. Pages with no main person are left out.","minItems":1,"type":"array","items":{"type":"string","enum":["18_24","25_34","35_44","45_54","55_plus"]}},"graphicShareMax":{"description":"The highest share of the latest posts that are text graphics, illustrations or memes, from 0 to 1, such as `0.5`.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false},"exclude":{"description":"Sent with a prompt, up to 5,000 Instagram creators you already have, by handle or profile URL. The search never judges, reads or returns them, so they cost nothing.","minItems":1,"maxItems":5000,"type":"array","items":{"type":"string","minLength":1,"maxLength":200}},"cursor":{"description":"The last answer's `next.cursor`, sent alone, to continue its search. Sending one again replays its answer for free.","type":"string","minLength":1,"maxLength":100}},"additionalProperties":false,"description":"A new search sends `prompt`, with `seeds`, `filters` and `exclude` if it has them. Every later call sends only `cursor`."},"CreatorToolRequest":{"type":"object","properties":{"handle":{"type":"string","minLength":1,"maxLength":200,"description":"The creator's Instagram handle, with or without the @, or their profile URL."}},"required":["handle"],"additionalProperties":false},"PartnershipsToolRequest":{"type":"object","properties":{"handle":{"type":"string","minLength":1,"maxLength":200,"description":"An Instagram handle, with or without the @, or a profile URL: a creator's, for the brands it worked with, or a brand's, for the creators who worked with it."}},"required":["handle"],"additionalProperties":false},"ContactToolRequest":{"type":"object","properties":{"handle":{"type":"string","minLength":1,"maxLength":200,"description":"The creator's handle, with or without the @, or their profile URL."},"platform":{"description":"Where `handle` lives: `instagram` (the default), `tiktok` or `youtube`. A profile URL says it already.","type":"string","enum":["instagram","tiktok","youtube"]}},"required":["handle"],"additionalProperties":false},"LookalikesToolRequest":{"type":"object","properties":{"seeds":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1,"maxLength":200},"description":"1 to 10 Instagram creators, by handle (with or without the @) or profile URL. What several seeds share counts more, so each seed added makes the list more specific."},"filters":{"type":"object","properties":{"country":{"description":"Where the creator lives, as ISO 3166 alpha-2 codes, such as `[\"US\"]`.","minItems":1,"type":"array","items":{"type":"string","pattern":"^[A-Z]{2}$"}},"language":{"description":"The language the creator posts in, as ISO 639-1 codes, such as `[\"en\"]`.","minItems":1,"type":"array","items":{"type":"string","pattern":"^[a-z]{2}$"}},"followers":{"description":"A follower range, either end optional.","type":"object","properties":{"min":{"type":"integer","minimum":0,"maximum":9007199254740991},"max":{"type":"integer","minimum":0,"maximum":9007199254740991}},"additionalProperties":false},"engagementMin":{"description":"The lowest engagement rate, in percent.","type":"number","minimum":0},"accountType":{"description":"The account types to return. Leaving it out returns people who make content: `real_creator`, `ugc_creator`, `expert`, `business_founder`, `artist`.","minItems":1,"type":"array","items":{"type":"string","enum":["real_creator","ugc_creator","expert","business_founder","brand_or_shop","meme_page","artist","media"]}},"gender":{"description":"Who the main person behind the account is: `woman`, `man`, `couple_or_family`. Pages with no main person are left out.","minItems":1,"type":"array","items":{"type":"string","enum":["woman","man","couple_or_family"]}},"ageBand":{"description":"How old the main person behind the account seems, by band: `18_24`, `25_34`, `35_44`, `45_54`, `55_plus`. Pages with no main person are left out.","minItems":1,"type":"array","items":{"type":"string","enum":["18_24","25_34","35_44","45_54","55_plus"]}},"graphicShareMax":{"description":"The highest share of the latest posts that are text graphics, illustrations or memes, from 0 to 1, such as `0.5`.","type":"number","minimum":0,"maximum":1}},"additionalProperties":false,"description":"Creators outside these are left out. Every filter is optional."},"limit":{"default":25,"description":"How many creators to return, up to 50.","type":"integer","minimum":1,"maximum":50}},"required":["seeds"],"additionalProperties":false},"EnrichResponse":{"type":"object","properties":{"handle":{"type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"callbackUrl":{"type":"string"},"customerId":{"type":"string"},"status":{"type":"string","enum":["completed","partial"]},"result":{"type":"object","properties":{"emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$"},"confidence":{"type":"number","minimum":0,"maximum":1}},"required":["email","confidence"],"additionalProperties":false}},"profile":{"type":"object","properties":{"firstName":{"type":"string"},"lastName":{"type":"string"},"country":{"type":"string"},"state":{"type":"string"},"city":{"type":"string"},"gender":{"type":"string","enum":["male","female"]},"phoneNumber":{"type":"string"}},"additionalProperties":false},"socialProfiles":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"username":{"type":"string"},"url":{"type":"string"},"followers":{"type":"number"}},"required":["platform"],"additionalProperties":false}}},"required":["emails","profile","socialProfiles"],"additionalProperties":false},"cached":{"type":"boolean"},"credits":{"type":"object","properties":{"charged":{"type":"integer","minimum":0,"maximum":9007199254740991},"remaining":{"type":["number","null"]}},"required":["charged","remaining"],"additionalProperties":false}},"required":["handle","platform","customerId","status","result","credits"],"additionalProperties":false},"AccountResponse":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"kind":{"type":"string","enum":["direct","internal"]},"credits":{"description":"The balance, kept to tenths of a credit; null for internal accounts.","type":["number","null"]},"pack":{"type":"object","properties":{"credits":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"priceUsd":{"type":"number"},"buyUrl":{"description":"Checkout link for the pack, tagged with the account id.","type":"string"}},"required":["credits","priceUsd"],"additionalProperties":false},"history":{"description":"The latest 20 credit movements, newest first.","type":"array","items":{"type":"object","properties":{"at":{"type":"string"},"type":{"type":"string","enum":["credit","usage"]},"credits":{"type":"number"},"ref":{"type":"string","description":"A payment id, `free:<account>`, or the `platform:handle` a charge paid for."},"item":{"description":"On a charge: what it paid for, such as `contact` or `profile`.","type":"string"},"note":{"type":"string"}},"required":["at","type","credits","ref"],"additionalProperties":false}},"usage":{"description":"Credits spent on each module over the last 30 days.","type":"object","properties":{"since":{"type":"string"},"items":{"type":"array","items":{"type":"object","properties":{"item":{"type":"string"},"charges":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"credits":{"type":"number"}},"required":["item","charges","credits"],"additionalProperties":false}}},"required":["since","items"],"additionalProperties":false}},"required":["id","name","kind","credits"],"additionalProperties":false},"LegacyError":{"type":"object","properties":{"error":{"type":"string","description":"A code such as `invalid_handle` or `upstream_unavailable`; on 401, a short message."}},"required":["error"],"additionalProperties":false},"LegacyInsufficientCredits":{"type":"object","properties":{"error":{"type":"string","const":"insufficient_credits"},"remaining":{"type":"number"},"buyUrl":{"description":"Checkout link for the next credit pack.","type":"string"}},"required":["error","remaining"],"additionalProperties":false},"LegacyRateLimited":{"type":"object","properties":{"error":{"type":"string","const":"rate_limited"},"retryAt":{"type":"string","description":"When to send the request again, ISO 8601 in UTC."}},"required":["error","retryAt"],"additionalProperties":false},"CreatorResponse":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"creator":{"$ref":"#/components/schemas/Creator"}},"required":["creator"],"additionalProperties":false},{"type":"null"}],"description":"Null in a quote."},"cost":{"$ref":"#/components/schemas/Cost"}},"required":["data","cost"],"additionalProperties":false},"Creator":{"type":"object","properties":{"id":{"anyOf":[{"type":"string","format":"uuid","pattern":"^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"},{"type":"null"}],"description":"The creator's id, null when we hold nothing on the account yet. It never changes."},"summary":{"type":"string","description":"A sentence or two written by code from the modules below, in a fixed order, ending with the date of the profile's numbers."},"profile":{"$ref":"#/components/schemas/Profile"},"analysis":{"description":"When asked for: `include: [\"analysis\"]`, or POST /api/v1/creator/analysis.","$ref":"#/components/schemas/Analysis"},"contact":{"description":"When asked for: `include: [\"contact\"]`, or POST /api/v1/creator/contact.","$ref":"#/components/schemas/Contact"},"partnerships":{"description":"When asked for: `include: [\"partnerships\"]`, or POST /api/v1/creator/partnerships.","$ref":"#/components/schemas/Partnerships"},"lookalikes":{"description":"When asked for: `include: [\"lookalikes\"]`, or POST /api/v1/creator/lookalikes.","oneOf":[{"type":"object","properties":{"status":{"type":"string","const":"ok"},"creators":{"type":"array","items":{"$ref":"#/components/schemas/Lookalike"},"description":"The creators we've analyzed that are most like this one, best first, up to 25, each with why it matched."},"asOf":{"type":"string","description":"When the list was made, from the creators we had analyzed by then."}},"required":["status","creators","asOf"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["not_found","private","unsupported","unavailable"]},"reason":{"type":"string","description":"Why the module is empty, and whether to try again."}},"required":["status","reason"],"additionalProperties":false}]}},"required":["id","summary","profile"],"additionalProperties":false},"Profile":{"type":"object","properties":{"status":{"type":"string","enum":["ok","private","unsupported","unavailable"],"description":"`ok`, `private`, `unsupported` (a platform we don't read yet) or `unavailable` (the read failed; retry later)."},"reason":{"description":"Why the account couldn't be read, when it couldn't.","type":"string"},"platform":{"type":"string","enum":["instagram","tiktok","youtube"]},"handle":{"type":"string"},"url":{"type":["string","null"]},"platformId":{"description":"The platform's permanent id for the account, which survives a handle change.","type":["string","null"]},"name":{"type":["string","null"]},"bio":{"type":["string","null"]},"links":{"type":"array","items":{"type":"string"},"description":"The links on the profile, as written."},"avatarUrl":{"description":"A lasting copy of the profile picture.","type":["string","null"]},"followers":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"following":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"postsCount":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"engagementRatePct":{"description":"Mean of (likes + comments) / followers over the latest posts, in percent, pinned posts and hidden likes left out.","type":["number","null"]},"avgReelViews":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Mean plays of the latest reels and videos, pinned ones left out."},"postsPerWeek":{"description":"Recent posts a week, pinned ones left out.","type":["number","null"]},"reelsSharePct":{"description":"Share of recent posts that are reels or videos, in percent.","type":["number","null"]},"lastPostAt":{"anyOf":[{"type":"string","description":"ISO 8601, UTC."},{"type":"null"}]},"verified":{"type":["boolean","null"]},"isBusiness":{"type":["boolean","null"]},"category":{"type":["string","null"]},"recentPosts":{"type":"array","items":{"$ref":"#/components/schemas/Post"},"description":"Up to 12, in profile order: pinned posts first, then newest first. Empty when the account couldn't be read."},"otherAccounts":{"type":"array","items":{"type":"object","properties":{"platform":{"type":"string"},"handle":{"type":"string"},"url":{"type":["string","null"]}},"required":["platform","handle","url"],"additionalProperties":false},"description":"The creator's accounts on other platforms. Link pages and websites are in `links`."},"asOf":{"anyOf":[{"type":"string","description":"ISO 8601, UTC."},{"type":"null"}],"description":"When the platform served the read these fields come from."}},"required":["status","platform","handle","url","platformId","name","bio","links","avatarUrl","followers","following","postsCount","engagementRatePct","avgReelViews","postsPerWeek","reelsSharePct","lastPostAt","verified","isBusiness","category","recentPosts","otherAccounts","asOf"],"additionalProperties":false},"Analysis":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","const":"ok"},"accountType":{"type":"string","enum":["real_creator","ugc_creator","expert","business_founder","brand_or_shop","meme_page","artist","media"],"description":"What kind of account it is, such as `real_creator` or `brand_or_shop`."},"topics":{"type":"array","items":{"type":"object","properties":{"topic":{"type":"string"},"confidence":{"type":"number"}},"required":["topic","confidence"],"additionalProperties":false},"description":"What it posts about, surest first, up to 8: IAB Content Taxonomy 3.1 topics and a few creator niches. What someone posts about, not whether they fit a brief."},"style":{"type":"object","properties":{"mainFormat":{"type":"string","enum":["talking","ugc_ads","tutorials","reviews_hauls","vlogs","routines","outfits","before_after","comedy","trends","educational","asmr","photo_dumps","behind_scenes"],"description":"The kind of content it makes most often, such as `talking` or `tutorials`."},"production":{"type":"string","enum":["lo_fi_phone","creator_polished","editorial","templated_branded"],"description":"How it's produced: `lo_fi_phone`, `creator_polished`, `editorial` or `templated_branded`."},"onCamera":{"type":"string","enum":["face_forward","sometimes","faceless","no_people"],"description":"How often a real face shows across the latest posts: half or more, a quarter or more, hands and bodies only, or no people."},"graphicSharePct":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Share of the latest posts that are text graphics, illustrations or memes, in percent."}},"required":["mainFormat","production","onCamera","graphicSharePct"],"additionalProperties":false},"creator":{"type":"object","properties":{"location":{"anyOf":[{"type":"object","properties":{"city":{"type":["string","null"]},"state":{"description":"A postal code in the US, Canada and Australia (FL, ON, NSW); null elsewhere.","type":["string","null"]},"country":{"type":"string","description":"ISO-2."}},"required":["city","state","country"],"additionalProperties":false},{"type":"null"}],"description":"Where the person or business behind the account lives or operates: what the bio says, else a contact record or the country the posts suggest, whichever we're surer of. Null when unsure."},"language":{"description":"ISO 639-1, the language of the bio and captions. Null when unsure.","type":["string","null"]},"gender":{"anyOf":[{"type":"string","enum":["woman","man","couple_or_family"]},{"type":"null"}]},"ageBand":{"anyOf":[{"type":"string","enum":["under_18","18_24","25_34","35_44","45_54","55_plus"]},{"type":"null"}]}},"required":["location","language","gender","ageBand"],"additionalProperties":false,"description":"About the person behind the account, never its audience. Null for pages with no main person."},"confidence":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{"type":"number"},"description":"How sure we are of each value above that isn't null, from 0 to 1, by field."},"asOf":{"type":"string","description":"When Jev analyzed the account."}},"required":["status","accountType","topics","style","creator","confidence","asOf"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["not_found","private","unsupported","unavailable"]},"reason":{"type":"string","description":"Why the module is empty, and whether to try again."}},"required":["status","reason"],"additionalProperties":false}]},"Contact":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","const":"ok"},"emails":{"type":"array","items":{"type":"object","properties":{"email":{"type":"string"},"confidence":{"type":"number","description":"How sure we are the inbox is the creator's, from 0 to 1."}},"required":["email","confidence"],"additionalProperties":false}},"name":{"description":"As a contact record lists it. Left out when it lists none.","type":"object","properties":{"first":{"type":["string","null"]},"last":{"type":["string","null"]}},"required":["first","last"],"additionalProperties":false},"asOf":{"type":"string","description":"When the email search ran."}},"required":["status","emails","asOf"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["not_found","unavailable"]},"reason":{"type":"string","description":"Why the module is empty, and whether to try again."}},"required":["status","reason"],"additionalProperties":false}]},"Partnerships":{"oneOf":[{"type":"object","properties":{"status":{"type":"string","const":"ok"},"posts":{"type":"array","items":{"$ref":"#/components/schemas/PartnershipPost"},"description":"Posts from the last 12 months in which the account and a brand (or, for a brand, a creator) name each other, newest first, up to 50."},"total":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991,"description":"How many such posts there are in all."},"asOf":{"type":"string","description":"When we last read the account's posts or its Tagged tab."}},"required":["status","posts","total","asOf"],"additionalProperties":false},{"type":"object","properties":{"status":{"type":"string","enum":["not_found","private","unsupported","unavailable"]},"reason":{"type":"string","description":"Why the module is empty, and whether to try again."}},"required":["status","reason"],"additionalProperties":false}]},"PartnershipPost":{"type":"object","properties":{"url":{"type":"string"},"postedAt":{"anyOf":[{"type":"string","description":"ISO 8601, UTC."},{"type":"null"}]},"postedBy":{"type":"string","description":"The handle that published it: the account asked about, or the partner."},"paid":{"description":"True when Instagram labels the post a paid partnership. False when a read saw no label, which isn't proof: our source doesn't always carry it. Null when the source can't see it, as on a Tagged tab.","type":["boolean","null"]},"brands":{"description":"When the account asked about is a creator: the brands the post names or is by.","type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"name":{"description":"As the account shows it, or as a tag named it.","type":["string","null"]},"kinds":{"type":"array","items":{"type":"string","enum":["collab","tag","mention"]},"description":"How the post names them: `collab` (coauthors), `tag` (tagged on the photo) or `mention` (an @ in the caption)."}},"required":["handle","name","kinds"],"additionalProperties":false}},"creators":{"description":"When the account asked about is a brand: the creators, with 1,500 followers or more, the post names or is by.","type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"name":{"description":"As the account shows it, or as a tag named it.","type":["string","null"]},"kinds":{"type":"array","items":{"type":"string","enum":["collab","tag","mention"]},"description":"How the post names them: `collab` (coauthors), `tag` (tagged on the photo) or `mention` (an @ in the caption)."},"followers":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["handle","name","kinds","followers"],"additionalProperties":false}}},"required":["url","postedAt","postedBy","paid"],"additionalProperties":false},"LookalikesResponse":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"seeds":{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"status":{"type":"string","enum":["ok","private","not_found","unavailable","not_analyzed"],"description":"`ok` when the seed counted; `private` or `not_found` on Instagram; `unavailable` when it couldn't be read or analyzed just now; `not_analyzed` when it has no posts to learn from."}},"required":["handle","status"],"additionalProperties":false},"description":"How each seed came out. Only `ok` seeds shape the list."},"creators":{"type":"array","items":{"$ref":"#/components/schemas/Lookalike"},"description":"The creators most like the seeds, best first."}},"required":["seeds","creators"],"additionalProperties":false},{"type":"null"}]},"cost":{"$ref":"#/components/schemas/Cost"}},"required":["data","cost"],"additionalProperties":false},"Lookalike":{"type":"object","properties":{"id":{"type":"string","description":"The creator's id. Send it to `/api/v1/creator` for the full picture."},"platform":{"type":"string","const":"instagram"},"handle":{"type":"string"},"platformId":{"description":"Instagram's permanent id for the account, which survives a handle change. Every account on a card was read, so it has one.","type":["string","null"]},"url":{"type":"string"},"name":{"type":["string","null"]},"followers":{"type":["number","null"]},"accountType":{"type":["string","null"]},"topTopics":{"type":"array","items":{"type":"string"},"description":"What the creator posts about most, up to three, in short words."},"summary":{"type":"string"},"match":{"type":"object","properties":{"score":{"type":"number","description":"How alike, from 0 to 1. Comparable within one answer, not across answers."},"why":{"type":"array","items":{"type":"string"},"description":"Why the creator matched, from shared topics, the same style and shared brands."}},"required":["score","why"],"additionalProperties":false}},"required":["id","platform","handle","platformId","url","name","followers","accountType","topTopics","summary","match"],"additionalProperties":false},"FindResponse":{"type":"object","properties":{"data":{"anyOf":[{"type":"object","properties":{"creators":{"type":"array","items":{"$ref":"#/components/schemas/FindCard"},"description":"Up to 10 matches, best first: match score, then engagement rate, then the newest post. A search never returns a creator twice."},"done":{"description":"Why the search ended, in one sentence. An answer with it has no `next`.","type":"string"}},"required":["creators"],"additionalProperties":false},{"type":"null"}]},"cost":{"$ref":"#/components/schemas/Cost"},"next":{"type":"object","properties":{"cursor":{"type":"string"},"pending":{"description":"Matches being read after this answer, which the next call returns if they still fit (`/api/v1/find`).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"callAfterSeconds":{"description":"When to send the cursor, in seconds, while matches are being read or the search looks beyond the creators we hold. Sooner gets a `409` `search_busy`.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hint":{"type":"string","description":"What sending the cursor returns."}},"required":["cursor","hint"],"additionalProperties":false}},"required":["data","cost"],"additionalProperties":false},"FindCard":{"type":"object","properties":{"id":{"type":"string","description":"The creator's id. Send it to `/api/v1/creator` for the full picture."},"platform":{"type":"string","const":"instagram"},"handle":{"type":"string"},"platformId":{"description":"Instagram's permanent id for the account, which survives a handle change. Every account on a card was read, so it has one.","type":["string","null"]},"url":{"type":"string"},"name":{"type":["string","null"]},"followers":{"type":["number","null"]},"accountType":{"type":["string","null"]},"topTopics":{"type":"array","items":{"type":"string"},"description":"What the creator posts about most, up to three, in short words."},"summary":{"type":"string"},"match":{"type":"object","properties":{"score":{"type":"number","description":"The weighted share of the creator's latest posts, up to 12, that suit the prompt: a post that fits counts 1, and one for the prompt's people on another subject 0.75. A match scores 0.2 or more, and when the prompt asks for creators who post about a subject, at least one of its posts fits."},"why":{"type":"array","items":{"type":"string"},"description":"The counts in words, such as \"9 of 12 recent posts fit the prompt, and 2 more are for the same people\"."},"posts":{"type":"array","items":{"type":"object","properties":{"url":{"type":"string"},"kind":{"type":"string","enum":["fits","audience"],"description":"`fits`: on the prompt's subject, for its people. `audience`: for the prompt's people, on another subject."}},"required":["url","kind"],"additionalProperties":false},"description":"Up to 3 of the posts that counted, best first."}},"required":["score","why","posts"],"additionalProperties":false},"readAt":{"description":"When we read the account, ISO 8601 in UTC. The card's numbers date from then, up to about 30 days ago.","type":["string","null"]}},"required":["id","platform","handle","platformId","url","name","followers","accountType","topTopics","summary","match","readAt"],"additionalProperties":false},"Post":{"type":"object","properties":{"url":{"type":"string"},"postedAt":{"anyOf":[{"type":"string","description":"ISO 8601, UTC."},{"type":"null"}]},"format":{"type":"string","enum":["reel","video","carousel","image"]},"caption":{"type":"string"},"likes":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Null when the creator hides them."},"comments":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]},"views":{"anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}],"description":"Plays, on reels and videos; null otherwise or when unknown."},"paidPartnership":{"description":"Whether Instagram labels the post a paid partnership. Null when the read couldn't see it.","type":["boolean","null"]},"pinned":{"type":"boolean","description":"Pinned to the top of the profile, so out of date order."}},"required":["url","postedAt","format","caption","likes","comments","views","paidPartnership","pinned"],"additionalProperties":false},"Cost":{"type":"object","properties":{"credits":{"type":"number","description":"Credits this call charged in total."},"balance":{"description":"Credits left after the call; null for internal accounts.","type":["number","null"]},"items":{"type":"array","items":{"$ref":"#/components/schemas/CostItem"}}},"required":["credits","balance","items"],"additionalProperties":false},"CostItem":{"type":"object","properties":{"module":{"type":"string","description":"A module of the request, such as `profile` or `contact`."},"credits":{"type":"number","description":"Credits this module cost, or would cost in a quote."},"charged":{"type":"boolean"},"reason":{"description":"Why nothing was charged: an email the account already unlocked, not delivered, an older copy because a fresh read failed, an internal account, or a quote, which charges nothing.","type":"string","enum":["unlocked","not_delivered","stale","internal","quote"]}},"required":["module","credits","charged"],"additionalProperties":false},"Error":{"type":"object","properties":{"error":{"type":"object","properties":{"code":{"type":"string","enum":["invalid_request","invalid_handle","unauthorized","insufficient_credits","insufficient_balance","forbidden","account_not_found","not_found","request_in_progress","search_busy","idempotency_key_reused","rate_limited","internal","upstream_unavailable"]},"message":{"type":"string","description":"What went wrong and what to do next, in one or two sentences."},"retryable":{"type":"boolean","description":"Whether sending the same request again can succeed."},"details":{"type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["code","message","retryable"],"additionalProperties":false}},"required":["error"],"additionalProperties":false},"FindToolResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"creators":{"type":"array","items":{"$ref":"#/components/schemas/FindCard"},"description":"Up to 10 matches, best first: match score, then engagement rate, then the newest post. A search never returns a creator twice."},"done":{"description":"Why the search ended, in one sentence. An answer with it has no `next`.","type":"string"}},"required":["creators"],"additionalProperties":false},"cost":{"$ref":"#/components/schemas/ToolCost"},"next":{"type":"object","properties":{"cursor":{"type":"string"},"pending":{"description":"Matches being read after this answer, which the next call returns if they still fit (`/api/v1/find`).","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"callAfterSeconds":{"description":"When to send the cursor, in seconds, while matches are being read or the search looks beyond the creators we hold. Sooner gets a `409` `search_busy`.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"hint":{"type":"string","description":"What sending the cursor returns."}},"required":["cursor","hint"],"additionalProperties":false}},"required":["data","cost"],"additionalProperties":false},"CreatorToolResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"creator":{"$ref":"#/components/schemas/Creator"}},"required":["creator"],"additionalProperties":false},"cost":{"$ref":"#/components/schemas/ToolCost"}},"required":["data","cost"],"additionalProperties":false},"LookalikesToolResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"seeds":{"type":"array","items":{"type":"object","properties":{"handle":{"type":"string"},"status":{"type":"string","enum":["ok","private","not_found","unavailable","not_analyzed"],"description":"`ok` when the seed counted; `private` or `not_found` on Instagram; `unavailable` when it couldn't be read or analyzed just now; `not_analyzed` when it has no posts to learn from."}},"required":["handle","status"],"additionalProperties":false},"description":"How each seed came out. Only `ok` seeds shape the list."},"creators":{"type":"array","items":{"$ref":"#/components/schemas/Lookalike"},"description":"The creators most like the seeds, best first."}},"required":["seeds","creators"],"additionalProperties":false},"cost":{"$ref":"#/components/schemas/ToolCost"}},"required":["data","cost"],"additionalProperties":false},"AccountToolResponse":{"type":"object","properties":{"data":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"balance":{"description":"Dollars left; null for internal accounts, which are never charged.","type":["number","null"]},"spend":{"type":"object","properties":{"since":{"type":"string","description":"The start of the 30 days counted, ISO 8601 in UTC."},"usd":{"type":"number","description":"Dollars charged since then, refunds taken off."},"tools":{"type":"array","items":{"type":"object","properties":{"tool":{"type":"string","enum":["find","creator","partnerships","contact","lookalikes","account"]},"calls":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"usd":{"type":"number"}},"required":["tool","calls","usd"],"additionalProperties":false},"description":"Each tool charged since then."}},"required":["since","usd","tools"],"additionalProperties":false,"description":"What the account spent over the last 30 days."}},"required":["id","name","balance","spend"],"additionalProperties":false},"cost":{"$ref":"#/components/schemas/ToolCost"}},"required":["data","cost"],"additionalProperties":false},"ToolCost":{"type":"object","properties":{"usd":{"type":"number","description":"What the call costs, in dollars: its tool's price, or 0 when it's free."},"charged":{"type":"boolean","description":"Whether the account paid it."},"reason":{"description":"Why nothing was charged: an internal account, or an answer replayed for free, for a find cursor sent again or an MCP call repeated with the same arguments within a day.","type":"string","enum":["internal","replay"]},"balance":{"description":"Dollars left after the call; null for internal accounts, which are never charged.","type":["number","null"]}},"required":["usd","charged","balance"],"additionalProperties":false}}},"paths":{"/api/v1/enrich":{"post":{"operationId":"enrich","summary":"Find a creator's email address.","description":"Looks up the email address and profile card of an Instagram, TikTok or YouTube creator and answers in the same request. A cold lookup can take a minute or two. Costs 1 credit when it returns an email for a creator your account hasn't unlocked. A miss, an error and a creator you already unlocked are free. Out of credits, a direct account gets 402 before any lookup runs.","externalDocs":{"url":"https://enrichment.socialgems.io/#enrich"},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichRequest"},"example":{"handle":"zendaya","platform":"instagram"}}}},"responses":{"200":{"description":"`status: \"completed\"` with the creator's emails, or `\"partial\"` when none was found.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EnrichResponse"},"example":{"handle":"zendaya","platform":"instagram","customerId":"acct_V1StGXR8_Z5j","status":"completed","result":{"emails":[{"email":"team@zendaya.com","confidence":0.9}],"profile":{"firstName":"Zendaya","gender":"female","country":"US","state":"California","city":"Los Angeles"},"socialProfiles":[{"platform":"tiktok","url":"https://tiktok.com/@zendaya"}]},"credits":{"charged":1,"remaining":259}}}}},"400":{"description":"The body or the handle is invalid: `invalid request body` or `invalid_handle`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyError"}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyError"}}}},"402":{"description":"A direct account out of credits, asking for a creator it hasn't unlocked. Nothing is charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyInsufficientCredits"},"example":{"error":"insufficient_credits","remaining":0,"buyUrl":"https://buy.stripe.com/example?client_reference_id=acct_V1StGXR8_Z5j"}}}},"403":{"description":"The key's account no longer exists: `account_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyError"}}}},"429":{"description":"Over the key's requests per minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyRateLimited"}}}},"503":{"description":"An upstream source failed or timed out: `upstream_unavailable`. Nothing is charged; retry after Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyError"}}}}}}},"/api/v1/account":{"get":{"operationId":"account","summary":"Check the balance and recent credit movements.","description":"The account behind the API key: its credit balance, the pack it can buy (250 credits for $29), its latest 20 credit movements and what it spent on each item over the last 30 days. New direct accounts start with 10 credits. Free to call.","externalDocs":{"url":"https://enrichment.socialgems.io/#account"},"security":[{"apiKey":[]}],"responses":{"200":{"description":"The account. Internal accounts have no balance, so `credits` is null and there's no pack, history or usage.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountResponse"},"example":{"id":"acct_V1StGXR8_Z5j","name":"Acme","kind":"direct","credits":259,"pack":{"credits":250,"priceUsd":29,"buyUrl":"https://buy.stripe.com/example?client_reference_id=acct_V1StGXR8_Z5j"},"history":[{"at":"2026-10-21T10:12:05.904Z","type":"usage","credits":-1,"ref":"instagram:zendaya","item":"contact"},{"at":"2026-10-20T16:02:11.517Z","type":"credit","credits":250,"ref":"pi_3Q","note":"250-credit pack"}],"usage":{"since":"2026-09-21T10:12:05.904Z","items":[{"item":"contact","charges":1,"credits":1}]}}}}},"401":{"description":"The API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyError"}}}},"403":{"description":"The key's account no longer exists: `account_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LegacyError"}}}}}}},"/api/v2/find":{"post":{"operationId":"v2Find","summary":"Find creators who fit what you describe in plain words, with the posts that show it, and a cursor for more.","description":"Describe the creators you want in `prompt` and put hard limits such as country, followers, gender or age band in `filters`. Each answer lists up to 10 matches, best first, each a short card with the date of our read, a match score, why it matched and up to 3 posts that show it. Send creators you already have in `exclude`, and the search never judges or returns them. A niche we've never searched can start with an empty answer while the search looks further; later calls bring what it finds. Send `next.cursor` alone for more, after `next.callAfterSeconds` when the answer gives it; sooner gets a free `409` `search_busy` with `Retry-After`. When the search can't find more, `data.done` says why and there's no `next`. $0.34 a call; a cursor sent again replays its answer for free. Instagram only.","externalDocs":{"url":"https://enrichment.socialgems.io/#find"},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindToolRequest"},"example":{"prompt":"Moms who post about getting organized, planners and productivity. Not accounts that sell their own planners.","filters":{"country":["US"],"followers":{"min":5000,"max":100000}},"exclude":["deskdiaries"]}}}},"responses":{"200":{"description":"Up to 10 matches, best first, what the call cost, and the cursor for the next call, or `data.done` when the search has ended.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/FindToolResponse"},"example":{"data":{"creators":[{"id":"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b","platform":"instagram","handle":"maya.plans","platformId":"1234567","url":"https://www.instagram.com/maya.plans","name":"Maya Plans","followers":48210,"accountType":"real_creator","topTopics":["journaling and planners","productivity"],"summary":"Real creator in New York, NY who talks to camera about journaling and planners, and productivity, shot on a phone. 48,210 followers, 3.4% engagement and about 4 posts a week, as of Oct 23, 2026.","readAt":"2026-10-23T09:12:00.000Z","match":{"score":0.875,"why":["9 of 12 recent posts fit the prompt, and 2 more are for the same people"],"posts":[{"url":"https://www.instagram.com/p/DPq1example/","kind":"fits"},{"url":"https://www.instagram.com/p/DPp4example/","kind":"fits"},{"url":"https://www.instagram.com/p/DPm2example/","kind":"audience"}]}}]},"cost":{"usd":0.34,"charged":true,"balance":28.66},"next":{"cursor":"fc_019a2b3c4d5e7f608a9b0c1d2e3f4a5b.2","pending":4,"callAfterSeconds":60,"hint":"1 match was ready and 4 more are being read. Send the cursor in about a minute to keep searching."}}}}},"400":{"description":"`invalid_request` (the body: a `prompt` and a `cursor` together, neither, or a cursor with anything else) or `invalid_handle`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: the API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`: the balance can't pay for the call. Nothing ran or was charged. A cursor's call, refused, can be sent again once the balance covers it.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden` (early access) or `account_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: none of your searches has this cursor.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`search_busy`: the search is still working. Send the cursor again after `Retry-After` seconds; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: over the key's requests per minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`upstream_unavailable`: we couldn't read the prompt or judge the creators' posts just now. Retry in a minute; nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v2/creator":{"post":{"operationId":"v2Creator","summary":"Get one Instagram creator's profile, latest posts and analysis.","description":"Send a handle or profile URL. The answer has the profile with its latest posts and the analysis: what the creator posts about, where they are, who they are and how their feed looks, with a one-line summary. Every field says when we read it. $0.01 a call; an account that is private, gone or has no posts to analyze is a `404` and free. Instagram only.","externalDocs":{"url":"https://enrichment.socialgems.io/#creator"},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorToolRequest"},"example":{"handle":"maya.plans"}}}},"responses":{"200":{"description":"The creator's profile and analysis, and what the call cost.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorToolResponse"},"example":{"data":{"creator":{"id":"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b","summary":"Real creator in New York, NY who talks to camera about journaling and planners, and productivity, shot on a phone. 48,210 followers, 3.4% engagement and about 4 posts a week, as of Oct 23, 2026.","profile":{"status":"ok","platform":"instagram","handle":"maya.plans","url":"https://www.instagram.com/maya.plans","platformId":"1234567","name":"Maya Plans","bio":"Planner girl in NYC","links":["https://linktr.ee/maya.plans"],"avatarUrl":"https://example.public.blob.vercel-storage.com/ig/avatars/1234567.jpg","followers":48210,"following":312,"postsCount":640,"engagementRatePct":3.42,"avgReelViews":21500,"postsPerWeek":4.2,"reelsSharePct":42,"lastPostAt":"2026-10-22T14:03:00.000Z","verified":false,"isBusiness":true,"category":"Creators & Celebrities","recentPosts":[{"url":"https://www.instagram.com/p/DPq1example/","postedAt":"2026-10-22T14:03:00.000Z","format":"reel","caption":"My week with @deskbloom, planner spread at the end","likes":1600,"comments":40,"views":21500,"paidPartnership":true,"pinned":false}],"otherAccounts":[{"platform":"tiktok","handle":"maya.plans","url":"https://www.tiktok.com/@maya.plans"}],"asOf":"2026-10-23T09:12:00.000Z"},"analysis":{"status":"ok","accountType":"real_creator","topics":[{"topic":"Journaling, Planners and Stationery","confidence":0.91},{"topic":"Productivity and Time Management","confidence":0.77}],"style":{"mainFormat":"talking","production":"lo_fi_phone","onCamera":"face_forward","graphicSharePct":8},"creator":{"location":{"city":"New York","state":"NY","country":"US"},"language":"en","gender":"woman","ageBand":"25_34"},"confidence":{"accountType":0.97,"mainFormat":0.81,"production":0.88,"location":0.96,"language":0.99,"gender":0.99,"ageBand":0.71},"asOf":"2026-10-23T09:12:05.000Z"}}},"cost":{"usd":0.01,"charged":true,"balance":28.99}}}}},"400":{"description":"`invalid_request` (the body) or `invalid_handle`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: the API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`: the balance can't pay for the call. Nothing ran or was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden` (early access) or `account_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such account on the platform, or nothing found for the tool, as `details.missing` says. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`request_in_progress`: a request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: the Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: over the key's requests per minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`upstream_unavailable`: our sources failed, so there was nothing to show. A retry can do better. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v2/partnerships":{"post":{"operationId":"v2Partnerships","summary":"See the brands an Instagram creator worked with, or the creators who worked with a brand.","description":"Send a creator's handle for the brands that appear in its posts from the last 12 months as paid partnerships, collabs, tags or mentions, or a brand's for the creators whose posts name it. $0.02 a call that finds posts; none is a `404` and free. Instagram only.","externalDocs":{"url":"https://enrichment.socialgems.io/#partnerships"},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PartnershipsToolRequest"},"example":{"handle":"maya.plans"}}}},"responses":{"200":{"description":"The account's profile and its partnership posts, newest first, and what the call cost.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorToolResponse"},"example":{"data":{"creator":{"id":"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b","summary":"48,210 followers, 3.4% engagement and about 4 posts a week, as of Oct 23, 2026.","profile":{"status":"ok","platform":"instagram","handle":"maya.plans","url":"https://www.instagram.com/maya.plans","platformId":"1234567","name":"Maya Plans","bio":"Planner girl in NYC","links":["https://linktr.ee/maya.plans"],"avatarUrl":"https://example.public.blob.vercel-storage.com/ig/avatars/1234567.jpg","followers":48210,"following":312,"postsCount":640,"engagementRatePct":3.42,"avgReelViews":21500,"postsPerWeek":4.2,"reelsSharePct":42,"lastPostAt":"2026-10-22T14:03:00.000Z","verified":false,"isBusiness":true,"category":"Creators & Celebrities","recentPosts":[{"url":"https://www.instagram.com/p/DPq1example/","postedAt":"2026-10-22T14:03:00.000Z","format":"reel","caption":"My week with @deskbloom, planner spread at the end","likes":1600,"comments":40,"views":21500,"paidPartnership":true,"pinned":false}],"otherAccounts":[{"platform":"tiktok","handle":"maya.plans","url":"https://www.tiktok.com/@maya.plans"}],"asOf":"2026-10-23T09:12:00.000Z"},"partnerships":{"status":"ok","posts":[{"url":"https://www.instagram.com/p/DPq1example/","postedAt":"2026-10-22T14:03:00.000Z","postedBy":"maya.plans","paid":true,"brands":[{"handle":"deskbloom","name":"Desk Bloom","kinds":["mention","tag"]}]},{"url":"https://www.instagram.com/p/DPm7example/","postedAt":"2026-10-09T17:40:00.000Z","postedBy":"papier","paid":null,"brands":[{"handle":"papier","name":"Papier","kinds":["tag"]}]}],"total":2,"asOf":"2026-10-23T09:12:00.000Z"}}},"cost":{"usd":0.02,"charged":true,"balance":28.98}}}}},"400":{"description":"`invalid_request` (the body) or `invalid_handle`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: the API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`: the balance can't pay for the call. Nothing ran or was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden` (early access) or `account_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such account on the platform, or nothing found for the tool, as `details.missing` says. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`request_in_progress`: a request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: the Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: over the key's requests per minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`upstream_unavailable`: our sources failed, so there was nothing to show. A retry can do better. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v2/contact":{"post":{"operationId":"v2Contact","summary":"Get a creator's email addresses, on Instagram, TikTok or YouTube.","description":"Send a handle or profile URL, and `platform` when a handle alone doesn't say it. The answer has the creator's own addresses, best first, and the name on record. $0.17 when it finds an email your account hasn't unlocked, $0.01 for one it has; none found is a `404` and free. A first lookup can take up to two minutes.","externalDocs":{"url":"https://enrichment.socialgems.io/#contact"},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactToolRequest"},"example":{"handle":"maya.plans"}}}},"responses":{"200":{"description":"The creator's profile and email addresses, and what the call cost.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatorToolResponse"},"example":{"data":{"creator":{"id":"019a1b2c-3d4e-7f60-8a9b-0c1d2e3f4a5b","summary":"48,210 followers, 3.4% engagement and about 4 posts a week, as of Oct 23, 2026.","profile":{"status":"ok","platform":"instagram","handle":"maya.plans","url":"https://www.instagram.com/maya.plans","platformId":"1234567","name":"Maya Plans","bio":"Planner girl in NYC","links":["https://linktr.ee/maya.plans"],"avatarUrl":"https://example.public.blob.vercel-storage.com/ig/avatars/1234567.jpg","followers":48210,"following":312,"postsCount":640,"engagementRatePct":3.42,"avgReelViews":21500,"postsPerWeek":4.2,"reelsSharePct":42,"lastPostAt":"2026-10-22T14:03:00.000Z","verified":false,"isBusiness":true,"category":"Creators & Celebrities","recentPosts":[{"url":"https://www.instagram.com/p/DPq1example/","postedAt":"2026-10-22T14:03:00.000Z","format":"reel","caption":"My week with @deskbloom, planner spread at the end","likes":1600,"comments":40,"views":21500,"paidPartnership":true,"pinned":false}],"otherAccounts":[{"platform":"tiktok","handle":"maya.plans","url":"https://www.tiktok.com/@maya.plans"}],"asOf":"2026-10-23T09:12:00.000Z"},"contact":{"status":"ok","emails":[{"email":"maya@mayaplans.com","confidence":0.8}],"name":{"first":"Maya","last":null},"asOf":"2026-10-23T09:13:00.000Z"}}},"cost":{"usd":0.17,"charged":true,"balance":28.83}}}}},"400":{"description":"`invalid_request` (the body) or `invalid_handle`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: the API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`: the balance can't pay for the call. Nothing ran or was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden` (early access) or `account_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: no such account on the platform, or nothing found for the tool, as `details.missing` says. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"`request_in_progress`: a request with the same Idempotency-Key is still running.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"`idempotency_key_reused`: the Idempotency-Key was used for a different request.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: over the key's requests per minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`upstream_unavailable`: our sources failed, so there was nothing to show. A retry can do better. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v2/lookalikes":{"post":{"operationId":"v2Lookalikes","summary":"Find the creators most like the ones you name: what they post about, how their feed looks, the brands they work with.","description":"Send 1 to 10 Instagram creators as seeds. The answer lists the creators we've analyzed that are most like them, best first, each a short card with a score and why it matched: the topics, style and brands they share. What several seeds share counts more. `filters` cut as find's do. Seeds we haven't read are read first, which can take up to about 40 seconds. $0.13 a call; a list that comes back empty is free. Instagram only.","externalDocs":{"url":"https://enrichment.socialgems.io/#lookalikes"},"security":[{"apiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookalikesToolRequest"},"example":{"seeds":["maya.plans","deskdiaries"],"filters":{"country":["US"],"followers":{"min":5000,"max":200000}},"limit":25}}}},"responses":{"200":{"description":"How each seed came out, the creators most like them, best first, and what the call cost.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/LookalikesToolResponse"},"example":{"data":{"seeds":[{"handle":"maya.plans","status":"ok"},{"handle":"deskdiaries","status":"ok"}],"creators":[{"id":"019a1b2c-4e5f-7a60-8b9c-0d1e2f3a4b5c","platform":"instagram","handle":"plannerpeace","platformId":"2345678","url":"https://www.instagram.com/plannerpeace","name":"Planner Peace","followers":31400,"accountType":"real_creator","topTopics":["journaling and planners","productivity","stationery"],"summary":"Real creator in Austin, TX who talks to camera about journaling and planners, and productivity, shot on a phone. 31,400 followers, 4.1% engagement and about 5 posts a week, as of Oct 24, 2026.","match":{"score":0.81,"why":["Posts about journaling and planners and productivity, like the seeds","Talks to camera, shot on a phone, like the seeds","Works with @deskbloom, as the seeds do"]}}]},"cost":{"usd":0.13,"charged":true,"balance":28.87}}}}},"400":{"description":"`invalid_request` (the body) or `invalid_handle`: a seed that isn't an Instagram handle or profile URL.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"`unauthorized`: the API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"`insufficient_balance`: the balance can't pay for the call. Nothing ran or was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden` (early access) or `account_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"`not_found`: none of the seeds is a public Instagram creator with posts to learn from. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"`rate_limited`: over the key's requests per minute.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"`upstream_unavailable`: none of the seeds could be read and analyzed just now. A retry can do better. Nothing was charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/api/v2/account":{"get":{"operationId":"v2Account","summary":"See your account's balance, and what it spent on each tool.","description":"Your account, its balance in dollars and what it spent on each tool over the last 30 days. Every other answer has the balance too, in `cost.balance`. Free.","externalDocs":{"url":"https://enrichment.socialgems.io/#account"},"security":[{"apiKey":[]}],"responses":{"200":{"description":"The account, its balance and its spend.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AccountToolResponse"},"example":{"data":{"id":"acct_V1StGXR8_Z5j","name":"Acme","balance":28.66,"spend":{"since":"2026-09-29T14:02:11.517Z","usd":1.28,"tools":[{"tool":"contact","calls":3,"usd":0.51},{"tool":"creator","calls":9,"usd":0.09},{"tool":"find","calls":2,"usd":0.68}]}},"cost":{"usd":0,"charged":false,"balance":28.66}}}}},"401":{"description":"`unauthorized`: the API key is missing, unknown or revoked.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"`forbidden` (early access) or `account_not_found`.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}