# 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
- get_business_hours (optional, string) — Get the business's hours
curl "https://www.socialcrawl.dev/v1/facebook/profile?url=https://www.facebook.com/Meta" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/facebook/profile/posts
List Facebook page posts
Credit cost: 1 (standard)
Parameters:
- url (optional, string) — Full URL of the Facebook page or profile to fetch posts for
- pageId (optional, string) — Facebook profile page id
- cursor (optional, string) — To paginate through the posts
- Constraint: one of url, pageId (at least one required)
curl "https://www.socialcrawl.dev/v1/facebook/profile/posts" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/facebook/post
Get Facebook post details
Credit cost: 1 (standard)
Parameters:
- url (required) — Full URL of the Facebook post
- get_comments (optional, boolean) — Whether you want to get the first several comments of the post
- get_transcript (optional, boolean) — Whether you want to get the transcript of the post
curl "https://www.socialcrawl.dev/v1/facebook/post?url=https://www.facebook.com/Meta/posts/1234567890" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/facebook/post/comments
List Facebook post comments
Credit cost: 1 (standard)
Parameters:
- url (optional, string) — Full URL of the Facebook post to fetch comments for
- 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.
- Constraint: one of url, feedback_id (at least one required)
curl "https://www.socialcrawl.dev/v1/facebook/post/comments" \
  -H "x-api-key: sc_your_api_key_here"

## 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
- cursor (optional, string) — The cursor to paginate to the next page
- Constraint: one of url, group_id (at least one required)
curl "https://www.socialcrawl.dev/v1/facebook/group/posts" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/facebook/post/transcript
Get Facebook video transcript
Credit cost: 10 (premium)
Parameters:
- url (required) — Full URL of the Facebook video post
curl "https://www.socialcrawl.dev/v1/facebook/post/transcript?url=https://www.facebook.com/Meta/videos/1234567890" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/facebook/profile/photos
List Facebook profile photos
Credit cost: 1 (standard)
Parameters:
- url (required) — Full URL of the Facebook page or profile
- next_page_id (optional, string) — To paginate through to the next page
- cursor (optional, string) — To paginate through to the next page
curl "https://www.socialcrawl.dev/v1/facebook/profile/photos?url=https://www.facebook.com/Meta" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/facebook/profile/reels
List Facebook profile reels
Credit cost: 1 (standard)
Parameters:
- url (required) — Full URL of the Facebook page or profile
- next_page_id (optional, string) — To paginate through to the next page
- cursor (optional, string) — To paginate through to the next page
curl "https://www.socialcrawl.dev/v1/facebook/profile/reels?url=https://www.facebook.com/Meta" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/facebook/adlibrary/ad
Get Facebook Ad Library ad details
Credit cost: 5 (advanced)
Parameters:
- id (optional, string) — Facebook Ad Library ad ID
- url (optional, string) — Facebook Ad URL
- get_transcript (optional, boolean) — Get the transcript of the ad. Only works if the video is under 2 minutes.
- trim (optional, boolean) — Set to true for a trimmed down version of the response
- Constraint: one of id, url (at least one required)
curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/ad" \
  -H "x-api-key: sc_your_api_key_here"

## GET /v1/facebook/adlibrary/company/ads
List Facebook Ad Library company ads
Credit cost: 5 (advanced)
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
- Constraint: one of pageId, companyName (at least one required)
curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/company/ads" \
  -H "x-api-key: sc_your_api_key_here"

## 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
curl "https://www.socialcrawl.dev/v1/facebook/adlibrary/search/ads?query=artificial intelligence" \
  -H "x-api-key: sc_your_api_key_here"

## 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 "https://www.socialcrawl.dev/v1/facebook/adlibrary/search/companies?query=Nike" \
  -H "x-api-key: sc_your_api_key_here"