# SocialCrawl API: facebook endpoints # Base URL: https://www.socialcrawl.dev # Auth: x-api-key header # Full docs: https://www.socialcrawl.dev/docs/facebook ## GET /v1/facebook/profile Get Facebook page profile Credit cost: 1 (standard) Parameters: - url (required): Full URL of the Facebook page or profile. A profile share link (`https://www.facebook.com/share/…`) is accepted. - get_business_hours (optional, string): Get the business's hours curl -G "https://www.socialcrawl.dev/v1/facebook/profile" \ --data-urlencode "url=https://www.facebook.com/Meta" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/profile/posts List Facebook page posts Credit cost: 1-4 (metered): 1 credit for the page. include=engagement holds 1 credit per row (3 rows a page) and keeps only the rows filled from a fresh lookup, so a page is at most 4 credits; rows served from cache are free, unfilled rows are refunded, and a repeat of the same call within the cache window costs 0. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. Parameters: - since (optional, string): Only posts published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Older posts are left off the page, and the page that reaches one ends the walk: `next_cursor` is not returned and `pagination.stopped_at` is `since`. Pinned posts sit out of date order and never end the walk. The page still costs what a page costs, so a daily poll pays for the pages it walks and no more. - stop_at_id (optional, string): The id (`post.id`) or URL (`post.url`) of the newest post you already hold. The page stops just before it: that post and everything after it are left off, `next_cursor` is not returned, and `pagination.stopped_at` is `known_id`. A pinned post never counts as the stop point. If it is not on this page the page is returned in full with its cursor, so keep walking. `pagination.stopped_at` is `end` when the list ran out first and `null` while there is more to walk. - url (optional, string): Full URL of the Facebook page or profile to fetch posts for. A profile share link (`https://www.facebook.com/share/…`) is accepted. - pageId (optional, string): Facebook profile page id - cursor (optional, string): To paginate through the posts - include (optional, enum: engagement): Set to `engagement` (one token only) to fill `post.engagement.shares` on every row, and `post.engagement.views` and `post.content.duration_seconds` on reels, in this one call. Holds 1 credit per row (3 a page) and keeps only the rows filled from a fresh lookup: rows already in cache and rows the lookup cannot fill are refunded, and a row with no public share count stays null and is free, so a page is never more than 4 credits and the usual bill is lower. A row that links to an event rather than a post is not looked up. The join takes 2 to 7 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged. - recent_days (optional, integer): Keep only posts published in the last N days (1 to 3650) and stop pagination once a page reaches older posts. Does not change the price of a page. - until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. - Constraint: one of url, pageId (at least one required) Worth sending: - since=2026-09-01: Returns only posts after this date, so a daily poll pays only for the pages with new posts. curl -G "https://www.socialcrawl.dev/v1/facebook/profile/posts" \ --data-urlencode "url=https://www.facebook.com/Meta" \ --data-urlencode "since=2026-09-01" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/post Get Facebook post details Credit cost: 1-2 (metered): 1 credit for the post. include=group holds 1 more and keeps it only when the group's name comes back, so a call with include=group is at most 2 credits; it is refunded when the post is not in a group, when the lookup fails, and when the group was looked up recently and is served from cache. Parameters: - url (required): Full URL of the Facebook post, reel or video. A share link from Facebook's Copy link (`https://www.facebook.com/share/v/…`, `/share/p/…`, `/share/r/…` or `/share/…`) is accepted and resolved to the post it names. - get_comments (optional, boolean): Accepted for backwards compatibility and currently a NO-OP: this endpoint returns the same body with or without it. Use `/v1/facebook/post/comments` (1 credit) for comments, passing the `post.ext.feedback_id` this response returns. - get_transcript (optional, boolean): Accepted for backwards compatibility and currently a NO-OP: this endpoint returns the same body with or without it. Use `/v1/facebook/post/transcript` for a video transcript. - include (optional, enum: group): Set to `group` (one token only) to fill `post.ext.group.name` and `post.ext.group.members` (the member count) on a post published in a Facebook group, in this one call. It costs 1 extra credit, kept only when the group's name comes back: a post that is not in a group, a lookup that fails and a group already in cache are refunded, so the call is never more than 2 credits. The lookup adds about 3 to 7 seconds when it runs, never more than 12, and nothing when the group is cached; read `data.hydration` for the credits held and kept and the time. The group's `id` and `url` are on every group post without it. curl -G "https://www.socialcrawl.dev/v1/facebook/post" \ --data-urlencode "url=https://www.facebook.com/OGCCopperfields/posts/pfbid02mAPifrgyzhGeAAhMGyNU4J2dFdFpAtTfb6p22yCQMHpzwqK9zh9XHS8Bm39tk7mwl" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/post/comments List Facebook post comments Credit cost: 1-5 (metered): 1 credit per page, with the default labels (sentiment, question, purchase_intent, complaint) included free. label=spam, toxic or low_quality holds 4 extra credits and refunds down to 1 credit per started 25 comments that were newly judged: comments already labelled are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. Parameters: - url (optional, string): Full URL of the Facebook post to fetch comments for. Share links (`/share/v/…`, `/share/p/…`, `/share/r/…`, `/share/…`) are accepted. - feedback_id (optional, string): Using feedback_id (instead of url) will *really* speed up the request. You can get the feedback_id when you make a request to /v1/facebook/post. - cursor (optional, string): Cursor to get more comments. Get 'cursor' from previous response. - label (optional, string): Optional CSV of SocialCrawl labels to add to every comment: sentiment, spam, question, purchase_intent, complaint, toxic, low_quality, injection. Without this param every page already carries sentiment, question, purchase_intent and complaint, free; label= adds the labels you name to them (the defaults keep running). Each comment gains computed.labels with probabilities (0 to 1), so you choose the cut-off; a comment that could not be judged carries labels: null. sentiment, question, purchase_intent and complaint are free when asked for too; spam, toxic, low_quality and injection add 1 credit per started 25 newly judged comments (comments already labelled for anyone are free, and so is a cached page). injection flags text that addresses an AI system and tries to direct it (flagged, p); it never drops or rewrites a row. judgments=off (or label=none) turns the default labels off. data.labels reports what was judged and billed. - exclude (optional, string): Optional CSV (spam, low_quality), only with the same preset in label. Drops comments whose probability is 0.8 or higher and lists their ids in data.labels.dropped_ids. A comment that could not be judged is never dropped. - judgments (optional, enum: on | off): Optional, on (the default) or off. By default every row gains free SocialCrawl judgments (computed.labels, and computed.relevance on search endpoints), reported in data.labels (mode default) and data.relevance (origin default), each with a status (complete, partial or skipped) and pending: the rows still being judged when the page was sent, which carry null now and are filled on your next call or cached read. Default judgments never add credits, never change an existing field, and never drop or reorder a row. off returns the page exactly as before, with none of those keys. label=none does the same. - dry_run (optional, enum: 1): Optional. When 1, return a cost preview for this labelled or relevance-filtered request without fetching the page or judging any row. data.estimate reports rows_expected, rows_cached, label_credits_min, label_credits_max and base_credits. 0 credits charged. - label_evidence (optional, enum: 1): Optional, only with label=. When 1, every labelled row also carries computed.labels_evidence. = { quote, sentence_index }: the sentence in the row that most clearly shows the label, copied verbatim. Absent or null when no single sentence shows it. - fit (optional, enum: goal): Optional. When goal, keep the rows and fields needed for the goal you pass in goal= (plus any that are uncertain, and the first and last), and replace the rest with a stub. data.held_back lists the held ids and a recall id that re-reads the full page from cache at no extra charge. Without this param the page is unchanged. - goal (optional, string): Required by fit=goal. What you are trying to do, in your own words, up to 300 characters. - fit_tokens (optional, integer): Optional, only with fit=goal. Soft cap on how much of the page to keep, in tokens. Uncertain blocks and the first and last block are kept even if they exceed it. - since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. - until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. - Constraint: one of url, feedback_id (at least one required) Worth sending: - label=purchase_intent: Marks each comment that shows buying intent, at no extra credits; sentiment, question and complaint are free too. curl -G "https://www.socialcrawl.dev/v1/facebook/post/comments" \ --data-urlencode "url=https://www.facebook.com/Meta/videos/a-slightly-life-changing-story/1459847961114516/" \ --data-urlencode "label=purchase_intent" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/group/posts List Facebook group posts Credit cost: 1 (standard) Parameters: - url (optional, string): Full URL of the Facebook group - group_id (optional, string): The ID of the group - sort_by (optional, enum: TOP_POSTS | RECENT_ACTIVITY | CHRONOLOGICAL | CHRONOLOGICAL_LISTINGS): How to sort the posts. CHRONOLOGICAL_LISTINGS reads the group's listings feed and can stall on some groups (a group with no listings feed does not answer); use the default sort, or CHRONOLOGICAL for posts in date order. - cursor (optional, string): Cursor to get the next page of posts. Take it from `pagination.next_cursor` on the previous response. - since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. - until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. - Constraint: one of url, group_id (at least one required) curl -G "https://www.socialcrawl.dev/v1/facebook/group/posts" \ --data-urlencode "url=https://www.facebook.com/groups/2204685680" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/group Get a Facebook group Credit cost: 1 (standard) Parameters: - url (optional, string): Full URL of the Facebook group. - group_id (optional, string): Numeric Facebook group id. - Constraint: one of url, group_id (at least one required) curl -G "https://www.socialcrawl.dev/v1/facebook/group" \ --data-urlencode "url=https://www.facebook.com/groups/2204685680" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/post/transcript Get Facebook video transcript Credit cost: 10 (premium) Parameters: - url (required): Full URL of the Facebook video post. Share links (`/share/v/…`, `/share/r/…`) are accepted. curl -G "https://www.socialcrawl.dev/v1/facebook/post/transcript" \ --data-urlencode "url=https://www.facebook.com/Meta/videos/a-slightly-life-changing-story/1459847961114516/" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/profile/photos List Facebook profile photos Credit cost: 1-9 (metered): 1 credit for the page. include=details holds 1 credit per photo (8 a page) and keeps only the rows filled from a fresh lookup, so a page is at most 9 credits; rows served from cache are free, unfilled rows are refunded, and a repeat of the same call within the cache window costs 0. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. Parameters: - url (required): Full URL of the Facebook page or profile. A profile share link (`https://www.facebook.com/share/…`) is accepted. - next_page_id (optional, string): To paginate through to the next page - cursor (optional, string): To paginate through to the next page - include (optional, enum: details): Set to `details` (one token only) to fill `post.author.display_name`, `post.author.avatar_url`, `post.ext.author_id`, `post.engagement.likes`, `.comments` and `.shares`, and `post.published_at` on every photo in this one call. Holds 1 credit per photo (8 a page) and keeps only the rows filled from a fresh lookup; rows already in cache and rows the lookup cannot fill are refunded, so a page is never more than 9 credits. A photo inside a multi-photo post carries its own counts, not the post's. The join takes 2 to 8 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged. - since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. - until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. curl -G "https://www.socialcrawl.dev/v1/facebook/profile/photos" \ --data-urlencode "url=https://www.facebook.com/Meta" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/profile/reels List Facebook profile reels Credit cost: 1 (standard) Parameters: - url (required): Full URL of the Facebook page or profile. A profile share link (`https://www.facebook.com/share/…`) is accepted. - next_page_id (optional, string): To paginate through to the next page - cursor (optional, string): To paginate through to the next page - recent_days (optional, integer): Keep only reels published in the last N days (1 to 3650) and stop pagination once a page reaches older reels. Does not change the price of a page. - since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. - until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. curl -G "https://www.socialcrawl.dev/v1/facebook/profile/reels" \ --data-urlencode "url=https://www.facebook.com/Meta" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/adlibrary/ad Get Facebook Ad Library ad details Credit cost: 5 (advanced) Parameters: - id (optional, string): Facebook Ad Library ad ID. Ad ids rotate as campaigns end, so take a current one from `/v1/facebook/adlibrary/company/ads` or `/v1/facebook/adlibrary/search/ads` rather than reusing an old one. - url (optional, string): Facebook Ad Library URL for the ad (`https://www.facebook.com/ads/library?id=...`). A page URL is rejected with a 400 at 0 credits. - trim (optional, boolean): Set to true for a trimmed down version of the response - Constraint: one of id, url (at least one required) Worth sending: - trim=true: Same price, lighter payload: drops the bulky raw fields. curl -G "https://www.socialcrawl.dev/v1/facebook/adlibrary/ad" \ --data-urlencode "id=1702938977100376" \ --data-urlencode "trim=true" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/adlibrary/company/ads List Facebook Ad Library company ads Credit cost: 5-35 (metered): 5 credits for the page. include=audience holds 1 credit per ad (30 a page) and keeps only the rows filled from a fresh lookup, so a page is at most 35 credits; rows served from cache are free, ads that never ran in the EU and other unfilled rows are refunded, and a repeat of the same call within the cache window costs 0. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. Parameters: - pageId (optional, string): Facebook page ID of the advertiser - companyName (optional, string): The name of the company. Can either use this or pageId - country (optional, string): This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL. - status (optional, enum: ALL | ACTIVE | INACTIVE): Status of the ad. Defaults to ACTIVE. - media_type (optional, enum: ALL | IMAGE | VIDEO | MEME | IMAGE_AND_MEME | NONE): Media type of the ad. Defaults to ALL. Meme refers to ads with image and text. Not sure why they call it meme. - language (optional, string): Language to filter ads on. Needs to be 2 letter language code, ie EN, ES, FR, etc - sort_by (optional, enum: total_impressions | relevancy_monthly_grouped): Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions. - start_date (optional, string): Start date to search for. Format: YYYY-MM-DD - end_date (optional, string): End date to search for. Format: YYYY-MM-DD - cursor (optional, string): Cursor to paginate through results - trim (optional, boolean): Set to true for a trimmed down version of the response - include (optional, enum: audience): Set to `audience` (one token only) to fill, on every ad that ran in the EU, `post.ext.ad.eu_total_reach`, `post.ext.ad.eu_reach_breakdown` (reach per EU country by age band and gender), `post.ext.ad.targets_eu`, `target_ages`, `target_gender` and `target_locations`. Holds 1 credit per ad (30 a page) and keeps only the rows filled from a fresh lookup; rows already in cache, ads that never ran in the EU and rows the lookup cannot fill are refunded, so a page is never more than 35 credits. The join takes 3 to 6 seconds on a fresh page, never more than 12 seconds a row, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged. - since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. - until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. - Constraint: one of pageId, companyName (at least one required) Worth sending: - trim=true: Same price, lighter payload: drops the bulky raw fields. curl -G "https://www.socialcrawl.dev/v1/facebook/adlibrary/company/ads" \ --data-urlencode "companyName=Lululemon" \ --data-urlencode "trim=true" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/adlibrary/search/ads Search Facebook Ad Library Credit cost: 5 (advanced) Parameters: - query (required): Search keyword or phrase to find ads in the Facebook Ad Library - sort_by (optional, enum: total_impressions | relevancy_monthly_grouped): Sort by impressions (high to low), or Most Recent (relevancy_monthly_grouped). Defaults to impressions. - search_type (optional, enum: keyword_unordered | keyword_exact_phrase): If you want to search by exact phrase or not - ad_type (optional, enum: all | political_and_issue_ads): Search for all ads or only political and issue ads - country (optional, string): This can only be one country. It has to be the 2 letter code for the country. It defaults to ALL. - status (optional, enum: ALL | ACTIVE | INACTIVE): Status of the ad. Defaults to ACTIVE. - media_type (optional, enum: ALL | IMAGE | VIDEO | MEME | IMAGE_AND_MEME | NONE): Media type of the ad. Defaults to ALL. Meme just means the ad has text and an image. No clue why they call it meme. - start_date (optional, string): Impressions start date. Needs to be in YYYY-MM-DD format. - end_date (optional, string): Impressions end date. Needs to be in YYYY-MM-DD format. - cursor (optional, string): Cursor to paginate through results - trim (optional, boolean): Set to true for a trimmed down version of the response - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. Worth sending: - trim=true: Same price, lighter payload: drops the bulky raw fields. curl -G "https://www.socialcrawl.dev/v1/facebook/adlibrary/search/ads" \ --data-urlencode "query=artificial intelligence" \ --data-urlencode "trim=true" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/adlibrary/search/companies Search Facebook Ad Library companies Credit cost: 5 (advanced) Parameters: - query (required): Search keyword or phrase to find companies in the Facebook Ad Library curl -G "https://www.socialcrawl.dev/v1/facebook/adlibrary/search/companies" \ --data-urlencode "query=Nike" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/profile/events List a Facebook page's events Credit cost: 1-9 (metered): 1 credit for the page. include=details holds 1 credit per event (8 a page) and keeps only the rows filled from a fresh lookup, so a page is at most 9 credits; rows served from cache are free, unfilled rows are refunded, and a repeat of the same call within the cache window costs 0. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. Parameters: - url (required): Full URL of the public Facebook page. - cursor (optional, string): Cursor returned by the previous response for pagination. - include (optional, enum: details): Set to `details` (one token only) to fill, on every event in this one call, `post.ext.event.description`, `address`, `latitude`, `longitude`, `hosts`, `host_context_text`, `category`, `privacy`, `attendance_count`, `interested_count` and `going_count`, the cover image on `post.content.thumbnail_url`, and the RSVP counts on `post.engagement.views` (interested) and `.likes` (going). Holds 1 credit per event (8 a page) and keeps only the rows filled from a fresh lookup; rows already in cache and rows the lookup cannot fill are refunded, so a page is never more than 9 credits. The join takes 2 to 6 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged. - since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. - until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. curl -G "https://www.socialcrawl.dev/v1/facebook/profile/events" \ --data-urlencode "url=https://www.facebook.com/brickyardoldtown" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/post/comment/replies List replies to a Facebook post comment Credit cost: 1-5 (metered): 1 credit per page, with the default labels (sentiment, question, purchase_intent, complaint) included free. label=spam, toxic or low_quality holds 4 extra credits and refunds down to 1 credit per started 25 comments that were newly judged: comments already labelled are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. Parameters: - feedback_id (required): `feedback_id` from `/v1/facebook/post/comments` for the parent comment (this is NOT the comment ID). - expansion_token (required): `expansion_token` from `/v1/facebook/post/comments` for the parent comment. - cursor (optional, string): Cursor returned by the previous response for pagination. - label (optional, string): Optional CSV of SocialCrawl labels to add to every comment: sentiment, spam, question, purchase_intent, complaint, toxic, low_quality, injection. Without this param every page already carries sentiment, question, purchase_intent and complaint, free; label= adds the labels you name to them (the defaults keep running). Each comment gains computed.labels with probabilities (0 to 1), so you choose the cut-off; a comment that could not be judged carries labels: null. sentiment, question, purchase_intent and complaint are free when asked for too; spam, toxic, low_quality and injection add 1 credit per started 25 newly judged comments (comments already labelled for anyone are free, and so is a cached page). injection flags text that addresses an AI system and tries to direct it (flagged, p); it never drops or rewrites a row. judgments=off (or label=none) turns the default labels off. data.labels reports what was judged and billed. - exclude (optional, string): Optional CSV (spam, low_quality), only with the same preset in label. Drops comments whose probability is 0.8 or higher and lists their ids in data.labels.dropped_ids. A comment that could not be judged is never dropped. - judgments (optional, enum: on | off): Optional, on (the default) or off. By default every row gains free SocialCrawl judgments (computed.labels, and computed.relevance on search endpoints), reported in data.labels (mode default) and data.relevance (origin default), each with a status (complete, partial or skipped) and pending: the rows still being judged when the page was sent, which carry null now and are filled on your next call or cached read. Default judgments never add credits, never change an existing field, and never drop or reorder a row. off returns the page exactly as before, with none of those keys. label=none does the same. - dry_run (optional, enum: 1): Optional. When 1, return a cost preview for this labelled or relevance-filtered request without fetching the page or judging any row. data.estimate reports rows_expected, rows_cached, label_credits_min, label_credits_max and base_credits. 0 credits charged. - label_evidence (optional, enum: 1): Optional, only with label=. When 1, every labelled row also carries computed.labels_evidence. = { quote, sentence_index }: the sentence in the row that most clearly shows the label, copied verbatim. Absent or null when no single sentence shows it. - fit (optional, enum: goal): Optional. When goal, keep the rows and fields needed for the goal you pass in goal= (plus any that are uncertain, and the first and last), and replace the rest with a stub. data.held_back lists the held ids and a recall id that re-reads the full page from cache at no extra charge. Without this param the page is unchanged. - goal (optional, string): Required by fit=goal. What you are trying to do, in your own words, up to 300 characters. - fit_tokens (optional, integer): Optional, only with fit=goal. Soft cap on how much of the page to keep, in tokens. Uncertain blocks and the first and last block are kept even if they exceed it. - since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. - until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. Worth sending: - label=purchase_intent: Marks each comment that shows buying intent, at no extra credits; sentiment, question and complaint are free too. curl -G "https://www.socialcrawl.dev/v1/facebook/post/comment/replies" \ --data-urlencode "feedback_id=ZmVlZGJhY2s6MzM3MzYxMzI5OTQ4Nzc1NV8xOTI5NTk0OTE3Njg3MTcz" \ --data-urlencode "expansion_token=MjoxNzc4NjM1MDM3OgF_JaMa3kMP9RIWC" \ --data-urlencode "label=purchase_intent" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/marketplace/location/search Search Facebook Marketplace locations Credit cost: 1 (standard) Parameters: - query (required): Location search query (city or area name). curl -G "https://www.socialcrawl.dev/v1/facebook/marketplace/location/search" \ --data-urlencode "query=Los Angeles" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/marketplace/search Search Facebook Marketplace listings Credit cost: 1 (standard) Parameters: - query (required): Search keyword (e.g., `bike`, `couch`). - lat (required): Latitude of the search location. - lng (required): Longitude of the search location. - radius_km (optional, integer): Search radius in kilometers. - min_price (optional, integer): Minimum listing price. - max_price (optional, integer): Maximum listing price. - count (optional, integer): Number of listings to return per page. - sort_by (optional, enum: suggested | distance_ascend | creation_time_descend | price_ascend | price_descend): Sort order for results. - delivery_method (optional, enum: all | local_pickup | shipping): Delivery filter: local pickup only, shipping only, or all. - condition (optional, enum: new | used_like_new | used_good | used_fair): Filter listings by item condition. - date_listed (optional, enum: all | 1 | 7 | 30 | last_24_hours | last_7_days | last_30_days): Filter by listing recency (relative window or numeric day count). - availability (optional, enum: available | sold | all): Filter by listing status: `available`, `sold`, or `all`. - cursor (optional, string): Opaque pagination cursor returned by the previous response: forward as-is. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. curl -G "https://www.socialcrawl.dev/v1/facebook/marketplace/search" \ --data-urlencode "query=bike" \ --data-urlencode "lat=40.7128" \ --data-urlencode "lng=-74.0060" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/marketplace/item Get a Facebook Marketplace item Credit cost: 1 (standard) Parameters: - id (optional, string): Facebook Marketplace item ID (numeric). - url (optional, string): Full URL of the Marketplace item. - Constraint: one of id, url (at least one required) curl -G "https://www.socialcrawl.dev/v1/facebook/marketplace/item" \ --data-urlencode "url=https://www.facebook.com/marketplace/item/1656586118821988/" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/events/search Search Facebook events by keyword Credit cost: 1 (standard) Parameters: - query (required): Event name or keyword to search for. - cursor (optional, string): Cursor returned by the previous response for pagination. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. curl -G "https://www.socialcrawl.dev/v1/facebook/events/search" \ --data-urlencode "query=dogs" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/events List Facebook events for a city Credit cost: 1-13 (metered): 1 credit for the page. include=details holds 1 credit per event (at most 12 a page) and keeps only the rows filled from a fresh lookup, so a page is at most 13 credits; rows served from cache are free, unfilled rows are refunded, and a repeat of the same call within the cache window costs 0. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. Parameters: - url (required): Full URL of the city's Facebook Events page. - time (optional, enum: today | this_week | next_week): Relative time window. Defaults to all time when omitted. - cursor (optional, string): Cursor returned by the previous response for pagination. - include (optional, enum: details): Set to `details` (one token only) to fill, on every event in this one call, `post.ext.event.description`, `address`, `city`, `latitude`, `longitude`, `hosts`, `host_context_text`, `category`, `privacy`, `is_canceled` and `attendance_count`, and the host credit on `post.author.display_name`. Holds 1 credit per event (at most 12 a page) and keeps only the rows filled from a fresh lookup; rows already in cache and rows the lookup cannot fill are refunded, so a page is never more than 13 credits. The join takes 2 to 8 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged. - since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. - until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. curl -G "https://www.socialcrawl.dev/v1/facebook/events" \ --data-urlencode "url=https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/event/details Get details for a Facebook event Credit cost: 1 (standard) Parameters: - id (optional, string): Facebook event ID (numeric). - url (optional, string): Full URL of the event. - Constraint: one of id, url (at least one required) curl -G "https://www.socialcrawl.dev/v1/facebook/event/details" \ --data-urlencode "url=https://www.facebook.com/events/4271394179613905/" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/adlibrary/ad/transcript Get a Facebook Ad Library video ad transcript Credit cost: 10 (premium) Parameters: - id (optional, string): Facebook Ad Library ad ID. Ad ids rotate as campaigns end, so take a current one from `/v1/facebook/adlibrary/company/ads` rather than reusing an old one. - url (optional, string): Facebook Ad Library URL for the ad. A page URL is rejected with a 400 at 0 credits. - Constraint: one of id, url (at least one required) curl -G "https://www.socialcrawl.dev/v1/facebook/adlibrary/ad/transcript" \ --data-urlencode "id=1126618083054464" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/profile/full Facebook profile, recent posts, and computed analytics in one call. Credit cost: 5 (override; tier standard) Parameters: - url (optional, string): Full Facebook profile or page URL. One of the identity params is required. - posts (optional, integer): How many of the fetched recent posts to return and compute the metrics over (1-100, default 25). One call reads one page, which on Facebook is 3 posts, so a larger value returns that page and a `_warnings` note; pass posts_cursor back as cursor for the next page. - cursor (optional, string): Pass a prior response's posts_cursor to read the next page of posts. Each call is a separate 5-credit call whose metrics cover that page only. - include (optional, string): CSV subset of posts,computed (default both). include=computed omits the raw posts[] array from the response to save payload. The metrics are computed from the same fetched posts either way, so they do not change. - Constraint: one of url (at least one required) curl -G "https://www.socialcrawl.dev/v1/facebook/profile/full" \ --data-urlencode "url=https://www.facebook.com/mrbeast" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/profile/reels/full Facebook profile reels with exact views, likes, comments, and shares merged in, in one call. Credit cost: 5-25 (metered): 5 credits per page of 10 reels - 1 for the list and 4 for the per-reel enrichment - which is roughly half what running the list-then-post-stats chain yourself costs. With no `limit` that is one page and a flat 5 credits. With `limit` set the endpoint walks `ceil(limit / 10)` pages, up to 5 for the 50 maximum (25 credits), holds that many up front and refunds every page it did not need. A page whose enrichment yields zero coverage refunds the 4-credit premium automatically, leaving the 1-credit list price Parameters: - url (required): Full URL of the Facebook page or profile. A profile share link (`https://www.facebook.com/share/…`) is accepted. - cursor (optional, string): Cursor from a prior response's next_cursor to page deeper. - limit (optional, integer): Return up to this many reels in one call (1-50). The endpoint pages the underlying list server-side until it has collected this many (or runs out), and bills per upstream page consumed (5 credits/page of 10). If the walk hits the internal time budget first, the response carries `_warnings: ["walk_deadline_reached"]`, unfetched pages are refunded, and `next_cursor` resumes where it stopped. Omit for a single page. curl -G "https://www.socialcrawl.dev/v1/facebook/profile/reels/full" \ --data-urlencode "url=https://www.facebook.com/Meta" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/search/posts Search Facebook posts by keyword Credit cost: 1-9 (metered): 1 credit per page. Relevance against your query (by default, or with relevance=) is free. Adding relevant_to= holds 4 extra credits and refunds down to 1 credit per started 25 rows that were newly judged: rows already judged for the same topic are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. The default labels (sponsored, intent, niche) are free. label=mention, quality, ai_style, ai_written, injection, or label=intent with offer=, holds 4 extra credits and refunds down to 1 credit per started 25 posts that were newly judged: posts already labelled are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. With `seen`, a page's price falls with its share of rows you already received under that id; credits for joined data (`include=`) are never discounted. Parameters: - query (required): Keyword or phrase to search for. - cursor (optional, string): Cursor from the previous response. - start_date (optional, string): Include posts on or after this date (YYYY-MM-DD). - end_date (optional, string): Include posts on or before this date (YYYY-MM-DD). - recent_posts (optional, boolean): When true, rank by recency instead of relevance. - location_uid (optional, string): Facebook location id to scope the search. - relevance (optional, enum: score | filter): Optional. Without this param every row already carries computed.relevance against your query, free ({ p, sense, depth, spam }: is this row about what your query means, or a different thing that shares its words?), and nothing is dropped or reordered. score asks for it explicitly and waits for every row; filter also drops the rows that are not about your query, and lists their ids in data.relevance.dropped_ids. Your query is the topic; nothing to configure. A row that could not be judged is never dropped and carries relevance: null. Pagination is unchanged, so a filtered page can hold fewer rows. Free with your query as the topic; with relevant_to it adds 1 credit per started 25 newly judged rows (rows already judged for the same topic are free, and so is a cached page). - relevance_threshold (optional, string): Optional, only with relevance. The probability (0 to 1) a row must reach to be kept by relevance=filter. Default 0.5. Lower keeps more rows, higher keeps fewer. - relevant_to (optional, string): Optional, only with relevance. Up to 200 characters describing what you mean, used as the topic instead of the query. Use it when the query is ambiguous, for example query=cleopatra with relevant_to=Cleopatra, the IGT slot game. - judgments (optional, enum: on | off): Optional, on (the default) or off. By default every row gains free SocialCrawl judgments (computed.labels, and computed.relevance on search endpoints), reported in data.labels (mode default) and data.relevance (origin default), each with a status (complete, partial or skipped) and pending: the rows still being judged when the page was sent, which carry null now and are filled on your next call or cached read. Default judgments never add credits, never change an existing field, and never drop or reorder a row. off returns the page exactly as before, with none of those keys. label=none does the same. - dry_run (optional, enum: 1): Optional. When 1, return a cost preview for this labelled or relevance-filtered request without fetching the page or judging any row. data.estimate reports rows_expected, rows_cached, label_credits_min, label_credits_max and base_credits. 0 credits charged. - fit (optional, enum: goal): Optional. When goal, keep the rows and fields needed for the goal you pass in goal= (plus any that are uncertain, and the first and last), and replace the rest with a stub. data.held_back lists the held ids and a recall id that re-reads the full page from cache at no extra charge. Without this param the page is unchanged. - goal (optional, string): Required by fit=goal. What you are trying to do, in your own words, up to 300 characters. - fit_tokens (optional, integer): Optional, only with fit=goal. Soft cap on how much of the page to keep, in tokens. Uncertain blocks and the first and last block are kept even if they exceed it. - label (optional, string): Optional CSV of SocialCrawl labels to add to every post. Without this param every page already carries sponsored, intent and niche, free; label= adds the labels you name to them (the defaults keep running). sponsored, intent and niche are free when asked for too; mention, quality, ai_style, intent with offer=, and injection add 1 credit per started 25 newly judged posts. judgments=off (or label=none) turns the default labels off. sponsored: is the post a paid or gifted promotion (p, 0 to 1), did it carry a disclosure marker such as #ad or 광고 (disclosed), is it likely paid with no marker (undisclosed), and which of the accounts it mentions does it promote (brand, or null). These are signals to review, never a finding. mention (needs brand=): is the post about that brand rather than something that shares its name (about_brand, 0 to 1), how it feels about the brand on five levels (sentiment_level 0 to 4 and sentiment_score 0 to 1, null when the post is not about the brand), is it sarcastic, which aspect it talks about (taste_or_quality, price_or_value, availability_or_delivery, health_or_safety, advertising_or_campaign, customer_service, none), and did the author buy or use it (first_hand). intent: what the author is mainly doing (label: asking_for_recommendation, comparing_options, switching_away, complaining, promoting, news_or_discussion, other, or null when unsure, with confidence), whether they read as a potential buyer rather than a seller (buyer, seller), how pressing the need is (urgency, 0 to 3), and, when you pass offer=, whether your offer would plausibly help them (fits_offer). niche: which of the 33 niches of the published taxonomy sc-niche-v1 the caption belongs to, or personal_no_niche, or other (label, confidence, taxonomy), with label null when the caption is too thin to tell or the pick is unsure. It reads the caption only, not the video. quality: how much checkable detail the caption carries (fact_density 0 to 3), whether it mainly asks for likes, replies, shares, follows or tags (engagement_bait, 0 to 1), whether it is written to provoke anger as a way to get engagement (rage_bait, 0 to 1; about the writing, never the side taken), whether it only repeats someone else's news or view (secondhand, 0 to 1), and what the post is mainly doing (post_aim: inform, opinion, sell, entertain, provoke, other). exclude=engagement_bait drops posts whose engagement_bait is 0.8 or higher. ai_style: writing patterns common in AI-generated text, judged on the text alone. It does not say who wrote the post, and a person who writes in this style is flagged too. Six patterns are judged, each a probability (0 to 1): binary_contrast ("This is not X. It's Y."), faux_insight ("Here's what nobody tells you" and throat-clearing openers), colon_reveal ("The best part: it learns."), profound_kicker (ends on an aphorism or mic-drop line), puffery ("marks a pivotal moment", "highlighting the importance of") and rhetorical_setup ("What if I told you", a question the post answers itself, "Not a X. Not a Y. A Z."). Four are counted in the text: slop_words (words and phrases such as delve, leverage, robust, game changer, at the end of the day), em_dashes, emoji_bullets (lines that start with an emoji or a symbol bullet) and one_line_paragraphs (paragraphs that are one short line). pattern_count is how many patterns are present (a judged pattern at 0.8 or higher, slop_words 1 or more, em_dashes 2 or more, emoji_bullets 2 or more, one_line_paragraphs 5 or more) and markers lists their names, comma-separated. A post with less than about eight words of text is only counted, with every judged pattern 0. The judged patterns read the first 400 and the last 150 characters of a long post, and the counts read the whole post. exclude=ai_style drops posts with 2 or more patterns. ai_written: how likely the post was written by an AI model, from SocialCrawl's own text classifier, reading the opening of the post (about 1,000 characters): p (0 to 1, calibrated), level (likely (p 0.95 or higher), possible (p 0.71 or higher) or unlikely) and model (the model name; a new name means a new scale). A post under 8 words is too short to read: p null, level too_short. It is a probability, not proof: a person can be flagged and an AI-written post can pass, and the shorter the post the less certain it is. exclude=ai_written drops likely posts. injection flags text that addresses an AI system and tries to direct it (flagged, p); it never drops or rewrites a row. A post that could not be judged carries labels: null. Posts already labelled for anyone are free, and so is a cached page. data.labels reports what was judged and billed. - exclude (optional, string): Optional CSV (engagement_bait, ai_style, ai_written). engagement_bait, only with label=quality, drops posts whose engagement_bait probability is 0.8 or higher. ai_style, only with label=ai_style, drops posts that show 2 or more of its writing patterns (pattern_count 2 or higher). ai_written, only with label=ai_written, drops posts whose level is likely (p 0.95 or higher), or whose p reaches your ai_written_threshold; a post too short to read is never dropped. Dropped posts are listed in data.labels.dropped_ids. A post that could not be judged is never dropped. - ai_written_threshold (optional, string): Optional, only with label=ai_written and exclude=ai_written. The p (0 to 1) at which exclude=ai_written drops a post. Default 0.95 (level likely). 0.71 also drops possible posts: more AI posts go, and more posts by people with them. - brand (optional, string): Required by label=mention, ignored otherwise. The brand or product the posts are judged against, up to 300 characters, for example brand=Buldak. Without it label=mention is skipped with the warning label_mention_needs_brand and is not billed. - brand_description (optional, string): Optional, with label=mention. One plain sentence saying what the brand is, for example brand_description=Samyang's spicy instant noodle brand. Use it when the name is also an ordinary word or another company's name. - offer (optional, string): Optional, with label=intent. One or two plain sentences saying what you sell, up to 300 characters, for example offer=A web design agency that builds websites for small businesses. Adds fits_offer to every post; without it fits_offer is null. - label_evidence (optional, enum: 1): Optional, only with label=. When 1, every labelled row also carries computed.labels_evidence. = { quote, sentence_index }: the sentence in the row that most clearly shows the label, copied verbatim. Absent or null when no single sentence shows it. - since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. - until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. - max_age_days (optional, integer): Keep only rows published within this many days (`post.published_at`), 1 to 3650. A row with no date is discarded. Filtering runs on our side after each page is fetched, so every page walked is billed as usual; `data.walk.discarded` counts what was removed and why. Each page is its own entry in `GET /v1/credits/transactions`, under the page's request id listed in `data.walk.request_ids`. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them (after any filter). Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows (after any filter), then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. - seen (optional, string): An id you choose (1 to 64 letters, digits, `.`, `_` or `-`). Rows your account already received under the same `seen` id are removed from the page, and the page price falls with the share of repeats: page credits x new rows / rows on the page, rounded up, so a page of nothing but repeats is free. Only the page's own price is discounted: credits for joined data (`include=`) are charged only for rows you have not received, and are never discounted. The memory lasts 24 hours from the last call that used the id, holds row ids only, and is private to your account. Use one id across a set of related searches; `data.walk.repeats` counts what was removed. Worth sending: - label=sponsored: Marks each post that is paid or sponsored, at no extra credits; intent and niche are free too. - relevance=filter: Drops rows that are not about your query, at no extra credits; relevance=score keeps them and adds a score. curl -G "https://www.socialcrawl.dev/v1/facebook/search/posts" \ --data-urlencode "query=NASA" \ --data-urlencode "label=sponsored" \ --data-urlencode "relevance=filter" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/search/pages Search Facebook pages by keyword Credit cost: 1-11 (metered): 1 credit for the page. include=details holds 1 credit per page (at most 10) and keeps only the rows filled from a fresh lookup, so a page is at most 11 credits; rows served from cache are free, unfilled rows are refunded, and a repeat of the same call within the cache window costs 0. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. Parameters: - query (required): Keyword or phrase to search for. - cursor (optional, string): Cursor from the previous response. - location_uid (optional, string): Facebook location id to scope the search. - include (optional, enum: details): Set to `details` (one token only) to fill `author.followers`, `author.bio`, `author.likes_count` and `author.joined_at` on every page in this one call. Holds 1 credit per page (at most 10) and keeps only the rows filled from a fresh lookup: rows already in cache and rows the lookup cannot fill are refunded, so a page is never more than 11 credits. The join takes 3 to 10 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. curl -G "https://www.socialcrawl.dev/v1/facebook/search/pages" \ --data-urlencode "query=NASA" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/search/people Search Facebook people by keyword Credit cost: 1 (standard) Parameters: - query (required): Name or phrase to search for. - cursor (optional, string): Cursor from the previous response. - location_uid (optional, string): Facebook location id to scope the search to a city. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. curl -G "https://www.socialcrawl.dev/v1/facebook/search/people" \ --data-urlencode "query=NASA" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/search/videos Search Facebook videos by keyword Credit cost: 1-8 (metered): 1 credit for the page. include=details holds 1 credit per video (7 a page) and keeps only the rows filled from a fresh lookup, so a page is at most 8 credits; rows served from cache are free, unfilled rows are refunded, and a repeat of the same call within the cache window costs 0. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. Parameters: - query (required): Keyword or phrase to search for. - cursor (optional, string): Cursor from the previous response. - start_date (optional, string): Include videos on or after this date (YYYY-MM-DD). - end_date (optional, string): Include videos on or before this date (YYYY-MM-DD). - recent_videos (optional, boolean): When true, rank by recency instead of relevance. - location_uid (optional, string): Facebook location id to scope the search. - include (optional, enum: details): Set to `details` (one token only) to fill `post.engagement.views`, `.likes`, `.comments` and `.shares`, `post.content.duration_seconds`, `post.published_at`, `post.author.avatar_url` and `post.ext.reaction_counts` on every video in this one call. Holds 1 credit per video (7 a page) and keeps only the rows filled from a fresh lookup: rows already in cache and rows the lookup cannot fill are refunded, so a page is never more than 8 credits. The join takes 3 to 5 seconds on a fresh page, never more than 12, and nothing when the rows are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged. - since (optional, string): Only rows published on or after this date: YYYY-MM-DD (midnight UTC) or an ISO 8601 timestamp. Rows older than it are left off each page. This list is not in date order, so the walk does not stop at the date: keep following `next_cursor`, and each page costs what a page costs even when every row on it is filtered out. A row with no date is kept. `published_after`, `start_date`, `from_date`, `publish_time` (`yesterday`, `this-week`, `this-month`, `last-3-months`, `last-6-months`) and `max_age_days` are accepted and applied as `since`. - until (optional, string): Only rows published on or before this date: YYYY-MM-DD (that whole UTC day is included) or an ISO 8601 timestamp. Newer rows are left off each page and the walk does not stop, so older pages follow. A row with no date is kept. `published_before`, `end_date` and `to_date` are accepted and applied as `until`. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. curl -G "https://www.socialcrawl.dev/v1/facebook/search/videos" \ --data-urlencode "query=NASA" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/search/groups Search Facebook groups by keyword Credit cost: 1-15 (metered): 1 credit for the page. include=details holds 1 credit per group (at most 10 a page) and keeps only the groups filled from a fresh lookup, so a page is at most 11 credits; groups served from cache are free, unfilled groups are refunded, and a repeat of the same call within the cache window costs 0. Relevance against your query (by default, or with relevance=) is free. Adding relevant_to= holds 4 extra credits and refunds down to 1 credit per started 25 rows that were newly judged: rows already judged for the same topic are free, a page where nothing could be judged refunds the whole extra, and a cached page is free. With `max_pages`, `max_items` or `max_credits`, each page walked is billed at this price (a cached page is free), and `max_credits` caps the total. Parameters: - query (required): Keywords describing the groups to find, for example `vintage cars`. Keywords only: the search is already limited to public Facebook groups, so a `site:` operator is refused before billing. - page (optional, integer): Page number, starting at 1. Forwarding `pagination.next_cursor` as `cursor` does the same. - include (optional, enum: details): Set to `details` (one token only) to fill, on every group in this one call, `author.followers` (members), `author.bio` (the description), `author.joined_at`, `author.ext.group.privacy_label`, `visibility_label`, `activity` and `id` (the numeric group id), and the name where it was null. Holds 1 credit per group (at most 10 a page) and keeps only the groups whose member count, description or activity was filled from a fresh lookup; groups already in cache and groups the lookup cannot fill are refunded, so a page is never more than 11 credits. The join takes 3 to 7 seconds on a fresh page, never more than 12, and nothing when the groups are already cached; read `data.hydration` for the rows, the credits held and kept, and the time. Without it the call is unchanged. - relevance (optional, enum: score | filter): Optional. Without this param every row already carries computed.relevance against your query, free ({ p, sense, depth, spam }: is this row about what your query means, or a different thing that shares its words?), and nothing is dropped or reordered. score asks for it explicitly and waits for every row; filter also drops the rows that are not about your query, and lists their ids in data.relevance.dropped_ids. Your query is the topic; nothing to configure. A row that could not be judged is never dropped and carries relevance: null. Pagination is unchanged, so a filtered page can hold fewer rows. Free with your query as the topic; with relevant_to it adds 1 credit per started 25 newly judged rows (rows already judged for the same topic are free, and so is a cached page). - relevance_threshold (optional, string): Optional, only with relevance. The probability (0 to 1) a row must reach to be kept by relevance=filter. Default 0.5. Lower keeps more rows, higher keeps fewer. - relevant_to (optional, string): Optional, only with relevance. Up to 200 characters describing what you mean, used as the topic instead of the query. Use it when the query is ambiguous, for example query=cleopatra with relevant_to=Cleopatra, the IGT slot game. - judgments (optional, enum: on | off): Optional, on (the default) or off. By default every row gains free SocialCrawl judgments (computed.labels, and computed.relevance on search endpoints), reported in data.labels (mode default) and data.relevance (origin default), each with a status (complete, partial or skipped) and pending: the rows still being judged when the page was sent, which carry null now and are filled on your next call or cached read. Default judgments never add credits, never change an existing field, and never drop or reorder a row. off returns the page exactly as before, with none of those keys. label=none does the same. - dry_run (optional, enum: 1): Optional. When 1, return a cost preview for this labelled or relevance-filtered request without fetching the page or judging any row. data.estimate reports rows_expected, rows_cached, label_credits_min, label_credits_max and base_credits. 0 credits charged. - fit (optional, enum: goal): Optional. When goal, keep the rows and fields needed for the goal you pass in goal= (plus any that are uncertain, and the first and last), and replace the rest with a stub. data.held_back lists the held ids and a recall id that re-reads the full page from cache at no extra charge. Without this param the page is unchanged. - goal (optional, string): Required by fit=goal. What you are trying to do, in your own words, up to 300 characters. - fit_tokens (optional, integer): Optional, only with fit=goal. Soft cap on how much of the page to keep, in tokens. Uncertain blocks and the first and last block are kept even if they exceed it. - max_pages (optional, integer): 1 to 50 (default 1, or 50 when `max_items` or `max_credits` is sent). Walk up to this many pages in one call and return the rows from all of them. Each page walked is billed exactly as one call to this endpoint (a cached page is free) and counts against your rate limit; its charge and any refund are recorded under the page's own request id, listed in `data.walk.request_ids`. The walk stops early at the last page, or when the request's time budget runs low; `data.walk.stopped` says why (`end`, `max_pages`, `max_items`, `max_credits`, `time_budget`, `page_error`) and `pagination.next_cursor` continues from where it stopped. - max_items (optional, integer): 1 to 5000. Get more in one call: keep walking pages until the response holds at least this many rows, then stop with `data.walk.stopped: "max_items"`. The last page is returned whole (it was billed), so `data.items` can hold up to one page more than this, and `pagination.next_cursor` resumes right after it without skipping a row. Walks up to 50 pages unless `max_pages` says fewer; each page is billed as one call (a cached page is free). Add `max_credits` to cap the spend. A long walk can stop on the time budget first (`"time_budget"`): send the returned cursor with the same params to continue. - max_credits (optional, integer): 1 to 100000. The most this call may spend, across every page it walks. A page starts only while the credits already spent plus that page's price (or, when higher, the most any page of this walk has cost) still fit, so the call never goes past it; the walk then stops with `data.walk.stopped: "max_credits"` and the cursor to resume. Sent alone, it walks as far as the budget goes (up to 50 pages). A value below the price of one page is a free 400 whose `error.details.page_credits` names that price. Credits a row join (`include=`) adds are known only once a page has run, so page 1 is checked against its own price. Worth sending: - relevance=filter: Drops rows that are not about your query, at no extra credits; relevance=score keeps them and adds a score. curl -G "https://www.socialcrawl.dev/v1/facebook/search/groups" \ --data-urlencode "query=vintage cars" \ --data-urlencode "relevance=filter" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/search/hashtag Search Facebook posts and videos carrying a hashtag Credit cost: 0-9 (metered): Metered, 0-9 credits: each call reads one page of /v1/facebook/search/videos (1 credit; with `since` or `until`, up to 8, since each video is looked up for its publish date at 1 credit, and a video still undated is left out) and /v1/facebook/search/posts (1 credit), each billed at that endpoint's own price exactly as a direct call is. A page that found nothing or failed costs nothing, and a page served from cache is free. A page is billed when it returned rows, even if none of them carried the hashtag; data.legs shows each page's charge and data.excluded what was left out. Parameters: - hashtag (required): One hashtag, with or without the #: letters, digits and _, no spaces. - cursor (optional, string): data.next_cursor from the previous response, sent back verbatim for the next page. - since (optional, string): Only posts published on or after this date, YYYY-MM-DD (UTC). - until (optional, string): Only posts published on or before this date, YYYY-MM-DD (UTC); that whole day is included. curl -G "https://www.socialcrawl.dev/v1/facebook/search/hashtag" \ --data-urlencode "hashtag=tractor" \ -H "x-api-key: YOUR_API_KEY" ## GET /v1/facebook/search/mentions Search Facebook posts that mention a page Credit cost: 0-1 (metered): Metered, 0-1 credits: each call reads one page of /v1/facebook/search/posts (1 credit), each billed at that endpoint's own price exactly as a direct call is. A page that found nothing or failed costs nothing, and a page served from cache is free. A page is billed when it returned rows, even if none of them carried the mention; data.legs shows each page's charge and data.excluded what was left out. Parameters: - handle (required): The page's username (facebook.com/), with or without the @, or its URL. Used to leave out the page's own posts. - cursor (optional, string): data.next_cursor from the previous response, sent back verbatim for the next page. - since (optional, string): Only posts published on or after this date, YYYY-MM-DD (UTC). - until (optional, string): Only posts published on or before this date, YYYY-MM-DD (UTC); that whole day is included. - name (optional, string): The name people write when they mention the page, for example Nykaa for facebook.com/mynykaa. Defaults to handle. - include_self (optional, boolean): When true, also keep posts by the account itself. Default false. curl -G "https://www.socialcrawl.dev/v1/facebook/search/mentions" \ --data-urlencode "handle=myntra" \ -H "x-api-key: YOUR_API_KEY"