Facebook Ad Transcript API

Facebook Ad Transcript

Features

• Ad Library URL batchesAccept Facebook Ad Library URLs from supported Facebook hosts and process each unique URL as an independent transcript target.
• Source-linked spoken textReturn non-empty transcript text with its submitted source URL and an identifier that falls back to the URL when no source ID is present.
• Language and format contextInclude a nullable source language, plaintext or WebVTT format, collection time, and optional shortcode in the normalized record.
• Available-only recordsSave a result only when the selected ad target yields non-empty transcript content, so a successful task can return fewer records than submitted URLs.

Parameters

How to Use

Submit Facebook Ad Library URLs, then reconcile returned source URLs because only targets with non-empty transcript text produce result items.

1. Prepare one or more Facebook Ad Library URLs whose host is facebook.com, www.facebook.com, or m.facebook.com and whose path contains /ads/library.
2. POST urls to /v1/facebook/ad-transcript, then store the returned task_id.
3. Poll /v1/tasks/{task_id} until the task succeeds or fails.
4. Read data.results.items, and when results.has_more is true request the next page with results.next_cursor.

curl -X POST "https://api.socq.ai/v1/facebook/ad-transcript" \
  -H "Authorization: Bearer $SOCQ_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://www.facebook.com/ads/library/?id=123456789012345"]}'

# Poll GET /v1/tasks/{task_id}
# Continue with GET /v1/tasks/{task_id}?limit=50&cursor={next_cursor}

Best Use Cases

• Advertising message review: Read source-linked transcript text to compare the spoken wording used across a selected set of public ad targets.
• Ad speech search indexing: Index text with record IDs, source URLs, collection times, and shortcode context so known ad transcripts can be searched by spoken terms.
• Transcript processing routing: Use language and format fields to route plaintext and WebVTT records into the appropriate text, subtitle, or language-processing pipeline.

Pro Tips

• Use a supported Facebook host and retain /ads/library in every URL path; other hosts or paths fail request validation.
• Canonicalize Ad Library URLs before batching when the same target appears with different query strings, because the collector removes only exact duplicate strings.
• Compare returned url values with the submitted list after success so unsupported ads and targets without non-empty transcript content remain visible to your workflow.
• Branch parsing on format and handle language and extra.shortcode as nullable values; created_at is reserved and currently returns null.
• Follow results.next_cursor while results.has_more is true when a large URL batch spans more than the requested result-page limit.

Related APIs