SocialCrawl

Creator email

Find the business email a creator publishes, with include=contacts on a profile call. What it searches, what comes back, how to retry, and what it costs

Add include=contacts to a profile call and the response carries the email address the creator publishes for business, with the place it was found. Nothing is guessed or generated: every address was read from a page the creator or their management put online, or from YouTube's View email address button.

To get the business email a creator publishes, for a creator you already have, call that creator's profile with include=contacts (/v1/youtube/channel/about, /v1/instagram/profile, /v1/tiktok/profile, /v1/twitter/profile or /v1/facebook/profile) and read author.ext.contacts; a data.contact_lookup.status of partial, gated_pending or unavailable means not yet, never no email. To find creators you do not have yet, call /v1/prism/creators first.

cURL
curl -G "https://www.socialcrawl.dev/v1/youtube/channel/about" \
  --data-urlencode "handle=creator" \
  --data-urlencode "include=contacts" \
  -H "x-api-key: YOUR_API_KEY"
Response (trimmed)
{
  "success": true,
  "data": {
    "author": {
      "ext": {
        "contacts": [
          {
            "kind": "email",
            "value": "business@example.com",
            "role": "management",
            "confidence": 0.92,
            "provenance": "published",
            "sources": [
              {
                "tier": "about",
                "url": "https://www.youtube.com/@creator/about",
                "snippet": "For business enquiries: business@example.com"
              }
            ]
          }
        ]
      }
    },
    "contact_lookup": {
      "status": "found",
      "checked_at": "2026-11-01T10:00:00.000Z",
      "recheck_after": "2027-04-30T10:00:00.000Z",
      "tiers_run": ["store", "about_page"],
      "pending": null
    }
  },
  "credits_used": 25
}

Which endpoints take it

EndpointWhere the search starts
youtube/channel/aboutThe channel's About page, then video descriptions
instagram/profile and instagram/profile/aboutThe profile's own text and links
tiktok/profileThe profile's own text and links
twitter/profileThe profile's own text and links
facebook/profileThe page's own text and links
linkbio/page and pillar/pageThe page's own email field

Send include=contacts on any of them. max_duration, min_confidence and roles work the same way on all of them except linkbio/page and pillar/page, which read one page and take only include.

What it searches

The search goes from the cheapest place to the most expensive and stops as soon as it has an address for the creator:

  1. Our store. An address we already found for this creator, from an earlier call by anyone. Nothing is fetched.
  2. The About page or bio. The creator's own text on the platform.
  3. Video descriptions (YouTube only).
  4. Linked profiles and link-in-bio pages. Only profiles and pages the creator links. We never guess a handle on another platform.
  5. The creator's own website. Read by SocialCrawlContactBot, which honors robots.txt. On Instagram, TikTok, X and Facebook the call waits for this read, inside max_duration. On YouTube it runs after the response, and the next call is answered from what it found.
  6. The View email address button (YouTube only). Some channels hide the address behind this button. Reading it is the one paid step, and it runs only when the places above found no address of the creator's own.

data.contact_lookup.tiers_run lists the places that ran, in order.

Read the response

Each entry of author.ext.contacts[] is one address:

FieldMeaning
valueThe email address.
roleown for the creator, management for a manager, agency for an agency.
confidence0 to 1. Higher means more confidence that the address belongs to this creator in that role. It is a ranking score from the source and the checks, not a measured accuracy, so read sources before you rely on an address.
provenancepublished when the creator put it on a page, gated_reveal when it came from the YouTube button.
sourcesWhere it was read. Each source has a tier (such as bio, about, video_description, link_in_bio, website or button), the url and a snippet of the text around the address.

data.contact_lookup says how the search ended:

statusFinal?Meaning
foundYesAt least one address is in author.ext.contacts.
none_publishedYesEvery place ran and the creator publishes no address. recheck_after says when it is worth asking again.
partialNoThe search ran out of time with places still being read, or the check of whose address a find is was still running. What was found so far is in the response.
gated_pendingNoThe address is behind the YouTube button and the read has not delivered yet.
unavailableNoA source failed on this call, or the check of whose address a find is could not finish, and nothing was found elsewhere. This does not mean the creator has no address.

On partial and gated_pending, data.contact_lookup.pending holds a reason, a retry_after_seconds and a doc_url that points at the entry on the errors page. Treat partial, gated_pending and unavailable as "not yet", never as "no email".

Retry an unsettled answer

The search carries on after a partial or gated_pending response and writes what it finds to our store. Wait retry_after_seconds, then send the same call again. The later call is served from the store.

Take the wait from retry_after_seconds every time and do not hard-code it. It is 30 seconds while the search is still running, 300 seconds while the View email address button is being read, and for a backup_queued reveal it follows the length of the queue: at least 1,800 seconds (30 minutes) and up to 21,600 seconds (6 hours) when the queue is long. For a wait that long, send async=true or store the channel and call again later, rather than holding a connection or a loop open.

cURL
# status is "partial", pending.retry_after_seconds is 30
sleep 30
curl -G "https://www.socialcrawl.dev/v1/youtube/channel/about" \
  --data-urlencode "handle=creator" \
  --data-urlencode "include=contacts" \
  -H "x-api-key: YOUR_API_KEY"
TypeScript
const KEY = process.env.SOCIALCRAWL_API_KEY!;
const sleep = (seconds: number) => new Promise((r) => setTimeout(r, seconds * 1000));

async function findEmail(handle: string, maxAttempts = 4) {
  const url = new URL("https://www.socialcrawl.dev/v1/youtube/channel/about");
  url.searchParams.set("handle", handle);
  url.searchParams.set("include", "contacts");

  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    const res = await fetch(url, { headers: { "x-api-key": KEY } });
    const body = await res.json();
    const lookup = body.data.contact_lookup;

    // found and none_published are final.
    if (lookup.status === "found" || lookup.status === "none_published") {
      return { status: lookup.status, contacts: body.data.author?.ext?.contacts ?? [] };
    }

    // partial, gated_pending and unavailable are not. Wait as told, then ask again.
    await sleep(lookup.pending?.retry_after_seconds ?? 30);
  }
  return { status: "unsettled", contacts: [] };
}
Python
import os, time, requests

def find_email(handle, max_attempts=4):
    for _ in range(max_attempts):
        res = requests.get(
            "https://www.socialcrawl.dev/v1/youtube/channel/about",
            params={"handle": handle, "include": "contacts"},
            headers={"x-api-key": os.environ["SOCIALCRAWL_API_KEY"]},
        )
        data = res.json()["data"]
        lookup = data["contact_lookup"]
        if lookup["status"] in ("found", "none_published"):
            return lookup["status"], (data.get("author", {}).get("ext", {}).get("contacts") or [])
        time.sleep((lookup.get("pending") or {}).get("retry_after_seconds", 30))
    return "unsettled", []

Cap the attempts, and set a client timeout of at least 60 seconds. max_duration limits the search, from 3 to 20 seconds (12 by default), and most calls answer within about 20 seconds. On Instagram, TikTok, X and Facebook a call whose profile links a website waits for that site inside max_duration, so the address from the site arrives in the first answer instead of the next one. The first read of a channel can take longer, because the profile read itself is not under that limit. A search that needs longer, such as a YouTube button reveal, carries on after the answer and saves what it finds, so the next call after retry_after_seconds is answered from that.

For a list of creators, add async=true and each call runs as a job that waits for the search to finish. It answers 202 with a job_id, and GET /v1/prism/jobs/{job_id} returns the result with its contact_status. A job does not answer partial. A button reveal that is still queued when the job ends comes back as gated_pending, so retry those later.

What it costs

youtube/channel/about charges its usual price only when the call returns an address. A call that ends in none_published, partial, gated_pending or unavailable on that endpoint is refunded.

On every other endpoint that takes include=contacts, the option costs nothing extra and the call costs its usual price whatever the status. An unsettled answer is not cached, so a retry is charged like any other call. On those endpoints, cap the attempts in your loop and wait the full retry_after_seconds between them.

Endpoint pricing lists the price of each endpoint.

Filter what comes back

ParameterDefaultEffect
rolesown,managementComma list of own, management and agency. Add agency to include agency addresses.
min_confidence0.60 to 1. Addresses below it are left out.
max_duration12Seconds the first call may spend searching before it answers, from 3 to 20. A longer value makes partial less likely.
cURL
curl -G "https://www.socialcrawl.dev/v1/instagram/profile" \
  --data-urlencode "handle=creator" \
  --data-urlencode "include=contacts" \
  --data-urlencode "roles=own,management,agency" \
  --data-urlencode "min_confidence=0.8" \
  -H "x-api-key: YOUR_API_KEY"

Report a wrong or bounced address

When an address bounces or belongs to someone else, tell us with POST /v1/feedback/contact, which is free. A bounce marks the stored address suspect, and a bounce from a second account removes it. The request body, the outcomes and the error cases are on the errors page.

cURL
curl -X POST "https://www.socialcrawl.dev/v1/feedback/contact" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "request_id": "req_V1StGXR8Z5jdHi6B", "email": "business@example.com", "outcome": "bounced" }'

Use addresses lawfully

An address being public does not make every use of it lawful. You decide how you use an address, and you are responsible for the marketing and privacy rules that apply to you, such as PECR and UK GDPR in the UK, CAN-SPAM in the US and the GDPR in the EU. Many creators are sole traders, and those rules can treat them as individuals. Honor opt-outs, and do not use an address for anything the terms prohibit. The Public Data Notice tells creators what we hold and how to have it removed.

Remove an address or block the crawler

A creator or site owner who wants an address removed, or the crawler kept off their site, can use the steps on the contact crawler page: add a Disallow rule for SocialCrawlContactBot to robots.txt, or write to socialcrawl@ridio.io with the domain or the address concerned.

Next steps