# Facebook on Onekey

> 29 endpoints for Facebook (0 stable, 29 beta), 2 to 3 credits each. Category: Social networks. One key, one JSON shape.

Base URL: https://api.onekey.dev
Auth: header `x-api-key: <key>`. Call shape: `GET /v1/{platform}/{endpoint}?{params}`.
Every response is `{success, data, metadata, error}`; check `success` first. Cost is in `metadata.credits_charged`. Free when served from cache (0.2 credit for a cached response over 100 KB). Failed and not-found calls are refunded.
Status: stable = verified against the live source; beta = not yet verified, fields may be missing.
Access: 26 of 29 endpoints are marked "needs a pack" or "may need a pack": free-grant credits reach only the open fetch path; a verified email and a purchased pack unlock the rest.

Page: https://onekey.dev/platforms/facebook
Reference (Markdown): https://onekey.dev/docs/api/facebook.md
All docs: https://onekey.dev/llms.txt

## Canonical fields returned

Unified-schema fields (same names on every platform), with how many of the 29 mapped Facebook endpoints return each:

- `content.text` (string): 17
- `content.createdAt` (ISO 8601 date): 14
- `content.id` (string): 12
- `engagement.likes` (integer): 11
- `entity.id` (string): 11
- `media.thumbnailUrl` (URL): 11
- `entity.url` (URL): 10
- `content.url` (URL): 9
- `entity.name` (string): 9
- `author.displayName` (string): 8
- `engagement.comments` (integer): 8
- `author.username` (string): 7
- `content.title` (string): 7
- `engagement.views` (integer): 7
- `entity.description` (string): 7
- `author.id` (string): 6
- `engagement.shares` (integer): 6
- `entity.location` (string): 5
- `author.avatarUrl` (URL): 4
- `author.followers` (integer): 3
- `author.url` (URL): 3
- `event.endDate` (ISO 8601 date): 3
- `event.startDate` (ISO 8601 date): 3
- `media.durationSeconds` (number): 3
- `author.verified` (boolean): 2
- `content.language` (string): 2
- `entity.createdAt` (ISO 8601 date): 2
- `entity.status` (string): 2
- `listing.currency` (string): 2
- `listing.price` (number): 2
- `listing.seller` (string): 2
- `media.url` (URL): 2
- `author.bio` (string): 1
- `author.contentCount` (integer): 1
- `author.following` (integer): 1
- `author.website` (URL): 1
- `entity.category` (string): 1
- `place.address` (string): 1
- `place.city` (string): 1
- `place.lat` (number): 1
- `place.lon` (number): 1
- plus 12 platform-specific fields under `ext.`

## Endpoints

### facebook.ad_library

Search the Facebook/Instagram Ad Library (public political/issue and EU ads) by keyword.
- Price: 2 credits per fresh call. Status: beta. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/ad_library?q=election` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search terms
  - `country` (string, optional, default US): ISO 3166 alpha-2 country
- Fields returned: `content.id`, `content.text`, `content.title`, `content.createdAt`, `author.id`, `author.displayName`, `content.url`
- Reference: https://onekey.dev/docs/api/facebook/ad_library.md

### facebook.adlibrary_ad

Get Facebook Ad Library ad details.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/facebook/adlibrary_ad?url=https%3A%2F%2Fwww.facebook.com%2Fnasa` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `url` (string, optional): Url (URL)
  - `id` (string, optional): Ad library ad id (alternative to url)
- Fields returned: `entity.id`, `author.displayName`, `content.text`, `content.createdAt`, `entity.status`, `media.url`, `entity.url`, `engagement.views`, `engagement.likes`
- Reference: https://onekey.dev/docs/api/facebook/adlibrary_ad.md

### facebook.adlibrary_ad_transcript

Get a Facebook Ad Library video ad transcript.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/facebook/adlibrary_ad_transcript?url=https%3A%2F%2Fwww.facebook.com%2Fnasa` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `url` (string, required): Url (URL)
- Fields returned: `content.text`, `content.language`, `media.durationSeconds`
- Reference: https://onekey.dev/docs/api/facebook/adlibrary_ad_transcript.md

### facebook.adlibrary_company_ads

List Facebook Ad Library company ads.
- Price: 3 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/adlibrary_company_ads?company_name=coffee` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `company_name` (string, optional): Company name
  - `page_id` (string, optional): Numeric Facebook page id (alternative to company_name)
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `entity.id`, `author.displayName`, `content.text`, `content.createdAt`, `entity.status`, `media.url`, `entity.url`, `engagement.views`, `engagement.likes`
- Reference: https://onekey.dev/docs/api/facebook/adlibrary_company_ads.md

### facebook.adlibrary_search_companies

Search Facebook Ad Library companies.
- Price: 3 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/adlibrary_search_companies?query=coffee` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `query` (string, required): Query
- Fields returned: `entity.id`, `entity.name`, `entity.url`, `entity.category`, `media.thumbnailUrl`, `ext.pageLikes`
- Reference: https://onekey.dev/docs/api/facebook/adlibrary_search_companies.md

### facebook.event_details

Get details for a Facebook event.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/facebook/event_details?url=https%3A%2F%2Fwww.facebook.com%2Fnasa` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `url` (string, optional): Url (URL)
  - `id` (string, optional): Facebook event id (alternative to url)
- Fields returned: `entity.id`, `entity.name`, `entity.url`, `entity.description`, `event.startDate`, `event.endDate`, `entity.location`, `ext.attendingCount`
- Reference: https://onekey.dev/docs/api/facebook/event_details.md

### facebook.events

List Facebook events for a city.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/events?url=https%3A%2F%2Fwww.facebook.com%2Fnasa` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `url` (string, required): Url (URL)
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `entity.id`, `entity.name`, `entity.url`, `entity.description`, `event.startDate`, `event.endDate`, `entity.location`, `ext.attendingCount`
- Reference: https://onekey.dev/docs/api/facebook/events.md

### facebook.events_search

Search Facebook events by keyword.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/events_search?query=coffee` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `query` (string, required): Query
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `entity.id`, `entity.name`, `entity.url`, `entity.description`, `event.startDate`, `event.endDate`, `entity.location`, `ext.attendingCount`
- Reference: https://onekey.dev/docs/api/facebook/events_search.md

### facebook.group

Get a Facebook group.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/facebook/group?url=https%3A%2F%2Fwww.facebook.com%2Fnasa` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `url` (string, optional): Url (URL)
  - `group_id` (string, optional): Facebook group id (alternative to url)
- Fields returned: `entity.id`, `entity.name`, `entity.url`, `entity.description`, `ext.memberCount`, `ext.privacy`
- Reference: https://onekey.dev/docs/api/facebook/group.md

### facebook.group_posts

List Facebook group posts.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/group_posts?url=https%3A%2F%2Fwww.facebook.com%2Fnasa` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `url` (string, required): Url (URL)
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `content.id`, `content.url`, `content.title`, `content.text`, `content.createdAt`, `engagement.likes`, `engagement.comments`, `engagement.shares`, `engagement.views`, `media.thumbnailUrl`, `author.username`
- Reference: https://onekey.dev/docs/api/facebook/group_posts.md

### facebook.marketplace_item

Get a Facebook Marketplace item.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/facebook/marketplace_item?url=https%3A%2F%2Fwww.facebook.com%2Fnasa` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `url` (string, optional): Url (URL)
  - `id` (string, optional): Marketplace item id (alternative to url)
- Fields returned: `entity.id`, `entity.name`, `entity.url`, `entity.description`, `listing.price`, `listing.currency`, `media.thumbnailUrl`, `listing.seller`, `entity.location`, `entity.createdAt`, `ext.rating`, `ext.reviewCount`, `ext.soldCount`
- Reference: https://onekey.dev/docs/api/facebook/marketplace_item.md

### facebook.marketplace_location_search

Search Facebook Marketplace locations.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/marketplace_location_search?query=coffee` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `query` (string, required): Query
- Fields returned: `entity.id`, `entity.name`, `place.address`, `place.city`, `place.lat`, `place.lon`
- Reference: https://onekey.dev/docs/api/facebook/marketplace_location_search.md

### facebook.marketplace_search

Search Facebook Marketplace listings.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/marketplace_search?query=coffee&lat=30.2672&lng=-97.7431` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `query` (string, required): Query
  - `lat` (string, required): Lat
  - `lng` (string, required): Lng
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `entity.id`, `entity.name`, `entity.url`, `entity.description`, `listing.price`, `listing.currency`, `media.thumbnailUrl`, `listing.seller`, `entity.location`, `entity.createdAt`, `ext.rating`, `ext.reviewCount`, `ext.soldCount`
- Reference: https://onekey.dev/docs/api/facebook/marketplace_search.md

### facebook.page

Facebook page: name, about, category, followers, likes, link, picture.
- Price: 2 credits per fresh call. Status: beta. Access: may need a pack. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/facebook/page?page=NASA` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `page` (string, required): Facebook page id or username, e.g. NASA
- Fields returned: `author.id`, `author.displayName`, `content.text`, `author.followers`, `engagement.likes`, `author.url`, `author.avatarUrl`, `author.website`, `ext.authorCategory`
- Reference: https://onekey.dev/docs/api/facebook/page.md

### facebook.page_events

Events of a Facebook page.
- Price: 2 credits per fresh call. Status: beta. Access: may need a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/page_events?page=NASA` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `page` (string, required): Facebook page id or username, e.g. NASA
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `content.id`, `content.title`, `content.text`, `content.createdAt`, `ext.location`, `ext.attending`
- Reference: https://onekey.dev/docs/api/facebook/page_events.md

### facebook.page_photos

Photos uploaded by a Facebook page.
- Price: 2 credits per fresh call. Status: beta. Access: may need a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/page_photos?page=NASA` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `page` (string, required): Facebook page id or username, e.g. NASA
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `content.id`, `content.text`, `content.createdAt`, `content.url`, `media.thumbnailUrl`
- Reference: https://onekey.dev/docs/api/facebook/page_photos.md

### facebook.page_posts

Recent public posts of a Facebook page.
- Price: 2 credits per fresh call. Status: beta. Access: may need a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/page_posts?page=NASA` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `page` (string, required): Facebook page id or username, e.g. NASA
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `content.id`, `content.text`, `content.createdAt`, `content.url`, `media.thumbnailUrl`, `engagement.shares`, `engagement.likes`, `engagement.comments`
- Reference: https://onekey.dev/docs/api/facebook/page_posts.md

### facebook.page_videos

Videos published by a Facebook page.
- Price: 2 credits per fresh call. Status: beta. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/page_videos?page=NASA` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `page` (string, required): Facebook page id or username, e.g. NASA
- Fields returned: `content.id`, `content.title`, `content.text`, `content.createdAt`, `content.url`, `media.durationSeconds`, `media.thumbnailUrl`, `engagement.views`
- Reference: https://onekey.dev/docs/api/facebook/page_videos.md

### facebook.post

A single Facebook post with reaction/comment/share counts.
- Price: 2 credits per fresh call. Status: beta. Access: may need a pack. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/facebook/post?post_id=54971236771_10161113987231772` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `post_id` (string, required): Facebook post id ({page_id}_{post_id})
- Fields returned: `content.id`, `content.text`, `content.createdAt`, `content.url`, `media.thumbnailUrl`, `engagement.shares`, `engagement.likes`, `engagement.comments`
- Reference: https://onekey.dev/docs/api/facebook/post.md

### facebook.post_comment_replies

List replies to a Facebook post comment.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/post_comment_replies?feedback_id=abc123&expansion_token=abc123` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `feedback_id` (string, required): Feedback id
  - `expansion_token` (string, required): Expansion token
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `content.id`, `content.text`, `content.createdAt`, `engagement.likes`, `engagement.comments`, `author.username`, `author.avatarUrl`
- Reference: https://onekey.dev/docs/api/facebook/post_comment_replies.md

### facebook.post_comments

Comments on a Facebook post.
- Price: 2 credits per fresh call. Status: beta. Access: may need a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/post_comments?post_id=54971236771_10161113987231772` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `post_id` (string, required): Facebook post id ({page_id}_{post_id})
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `content.id`, `content.text`, `content.createdAt`, `author.id`, `author.displayName`, `engagement.likes`, `engagement.comments`
- Reference: https://onekey.dev/docs/api/facebook/post_comments.md

### facebook.post_transcript

Get Facebook video transcript.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/facebook/post_transcript?url=https%3A%2F%2Fwww.facebook.com%2Fnasa` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `url` (string, required): Url (URL)
- Fields returned: `content.text`, `content.language`, `media.durationSeconds`
- Reference: https://onekey.dev/docs/api/facebook/post_transcript.md

### facebook.profile_full

Facebook profile, recent posts, and computed analytics in one call.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: one record.
- Request: `GET https://api.onekey.dev/v1/facebook/profile_full?url=https%3A%2F%2Fwww.facebook.com%2Fnasa` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `url` (string, required): Url (URL)
- Fields returned: `author.id`, `author.username`, `author.displayName`, `author.bio`, `author.followers`, `author.following`, `author.contentCount`, `author.verified`, `author.avatarUrl`, `author.url`, `ext.recentPosts`, `ext.analytics`
- Reference: https://onekey.dev/docs/api/facebook/profile_full.md

### facebook.profile_reels_full

Facebook profile reels with exact views, likes, comments, and shares merged in, in one call.
- Price: 3 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/profile_reels_full?url=https%3A%2F%2Fwww.facebook.com%2Fnasa` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `url` (string, required): Url (URL)
- Fields returned: `content.id`, `content.url`, `content.title`, `content.text`, `content.createdAt`, `engagement.likes`, `engagement.comments`, `engagement.shares`, `engagement.views`, `media.thumbnailUrl`, `author.username`
- Reference: https://onekey.dev/docs/api/facebook/profile_reels_full.md

### facebook.search_groups

Search Facebook groups by keyword.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/search_groups?query=coffee` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `query` (string, required): Query
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `entity.id`, `entity.name`, `entity.url`, `entity.description`, `ext.memberCount`, `ext.privacy`
- Reference: https://onekey.dev/docs/api/facebook/search_groups.md

### facebook.search_pages

Search public Facebook pages by name (Pages Search, needs Page Public Metadata Access).
- Price: 2 credits per fresh call. Status: beta. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/search_pages?q=nasa` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `q` (string, required): Search text
- Fields returned: `author.id`, `author.displayName`, `author.url`, `ext.authorCategory`
- Reference: https://onekey.dev/docs/api/facebook/search_pages.md

### facebook.search_people

Search Facebook people by keyword.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/search_people?query=coffee` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `query` (string, required): Query
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `author.id`, `author.username`, `author.displayName`, `author.followers`, `author.verified`, `author.avatarUrl`
- Reference: https://onekey.dev/docs/api/facebook/search_people.md

### facebook.search_posts

Search Facebook posts by keyword.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/search_posts?query=coffee` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `query` (string, required): Query
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `content.id`, `content.url`, `content.title`, `content.text`, `content.createdAt`, `engagement.likes`, `engagement.comments`, `engagement.shares`, `engagement.views`, `media.thumbnailUrl`, `author.username`
- Reference: https://onekey.dev/docs/api/facebook/search_posts.md

### facebook.search_videos

Search Facebook videos by keyword.
- Price: 2 credits per fresh call. Status: beta. Access: needs a pack. Returns: a list.
- Request: `GET https://api.onekey.dev/v1/facebook/search_videos?query=coffee` with header `x-api-key: YOUR_API_KEY`
- Parameters:
  - `query` (string, required): Query
  - `cursor` (string, optional): Opaque cursor from a previous response's `pagination.next_cursor`. Omit for the first page.
- Fields returned: `content.id`, `content.url`, `content.title`, `content.text`, `content.createdAt`, `engagement.likes`, `engagement.comments`, `engagement.shares`, `engagement.views`, `media.thumbnailUrl`, `author.username`
- Reference: https://onekey.dev/docs/api/facebook/search_videos.md

## Sample request

```bash
curl "https://api.onekey.dev/v1/facebook/adlibrary_ad?url=https%3A%2F%2Fwww.facebook.com%2Fnasa" \
  -H "x-api-key: YOUR_API_KEY"
```