# Event

Schemas

Public events with their start and end, time zone, venue or online flag, hosts, categories, ticket link and attendance.

## Endpoints

4 endpoints return events on Facebook Events.

- [GETFacebook Event API`/v1/facebook/event`](https://socialtap.dev/docs/reference/facebook/event/index.md)
- [GETFacebook Page Events API`/v1/facebook/events`](https://socialtap.dev/docs/reference/facebook/events/index.md)
- [GETFacebook City Events API`/v1/facebook/place_events`](https://socialtap.dev/docs/reference/facebook/place_events/index.md)
- [GETFacebook Event Search API`/v1/facebook/search_events`](https://socialtap.dev/docs/reference/facebook/search_events/index.md)

## Schema

Single-item endpoints return this object as `data`; list endpoints return an array of them as `data` with a [`page`](https://socialtap.dev/docs/pagination/index.md) object. The standard [`meta`](https://socialtap.dev/docs/reference/index.md#meta) comes with every response.

| Field | Type | Description |
| --- | --- | --- |
| `platform` | `string` | Platform ID (facebook, …). |
| `id` | `string` | Platform-native event ID (string; Facebook's numeric event ID). |
| `url` | `string` (uri) | Canonical event page URL (https://www.facebook.com/events/\<id>/). |
| `name` | `string` | The event's name as its page shows it. |
| `description` | `string` or `null` | Its description as plain text; null when it has none. |
| `status` | `string` | At fetch time: scheduled (not started), ongoing (started, not over), ended (over), canceled (called off by its hosts); unknown when the source that answered does not show it (a fallback whose results hold only a name and a picture). New values may be added; treat any other value as unknown.<br>One of `scheduled`, `ongoing`, `ended`, `canceled`, `unknown` |
| `start_at` | `string` (date-time) or `null` | When it starts, RFC 3339 UTC; null only when the platform shows no start. |
| `end_at` | `string` (date-time) or `null` | When it ends, RFC 3339 UTC; null when its hosts set no end or the platform does not show it. |
| `time_zone` | `string` or `null` | The event's IANA time zone (America/New_York) when the platform states one; null otherwise (utc_offset_minutes still gives its local time). |
| `utc_offset_minutes` | `integer` or `null` | The event's offset from UTC at its start, in minutes (-240 for 5:00 PM EDT): its local start time is start_at plus this offset; null when unknown. |
| `is_online` | `boolean` or `null` | Held online (a stream or video call) rather than at a venue. |
| `place` | `object` or `null` | Where it is held; null for an online event with no venue or when not shown. |
| `place.id` | `string` or `null` | The place's ID as the platform's place endpoints key it (place.id); null for a venue given as free text. |
| `place.name` | `string` or `null` | The place's name as shown (a venue's name, or the text its host typed). |
| `place.url` | `string` (uri) or `null` | The place's page URL; null for a venue given as free text. |
| `place.address` | `string` or `null` | Address as the platform shows it (one line, not normalized). |
| `place.city` | `string` or `null` | City or locality, as shown. |
| `place.country_code` | `string` or `null` | ISO 3166-1 alpha-2 country of the place. |
| `place.latitude` | `number` or `null` | WGS 84 latitude in degrees; null when the platform shows no coordinates (set together with longitude). |
| `place.longitude` | `number` or `null` | WGS 84 longitude in degrees; null when the platform shows no coordinates (set together with latitude). |
| `hosts` | `object[]` | The accounts hosting it (pages and people), the main organizer first; \[\] when none are shown (listed in unknown_fields when the source cannot see them). |
| `hosts[].id` | `string` or `null` | Platform-native account ID; null when only the handle is known. |
| `hosts[].username` | `string` or `null` | Handle without the @; null when the account has none. |
| `hosts[].display_name` | `string` or `null` | Display name shown on the profile. |
| `hosts[].url` | `string` (uri) or `null` | Canonical profile URL. |
| `hosts[].avatar_url` | `string` (uri) or `null` | Profile picture URL. Platform CDN URLs can expire within hours. |
| `hosts[].is_verified` | `boolean` or `null` | Platform verification badge; null where the platform has no badge. |
| `cover_url` | `string` (uri) or `null` | The event's cover image (a video cover's poster frame); null when it has none. Platform CDN URLs can expire within days. |
| `categories` | `string[]` | Categories the platform files it under, as shown (not normalized), the main one first; \[\] when none. |
| `ticket_url` | `string` (uri) or `null` | Where to buy tickets or register, as the platform links it; null when none is linked. |
| `parent_id` | `string` or `null` | ID of the event series this date belongs to (a recurring event's parent event); null for a single event or the series itself. |
| `community_id` | `string` or `null` | ID of the community it belongs to (the Facebook group it was created in; community.id); null when none. |
| `metrics` | `object` | Counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `metrics.attendee_count` | `integer` or `null` | People who said they are going (after the event: who went), as the platform counts them; null when not shown. |
| `platform_specific` | `object` | Fields only this platform has, under its ID (platform_specific.\<platform>); each null when unknown. |
| `platform_specific.facebook` | `object` or `null` | A Facebook event's own fields. |
| `platform_specific.facebook.ticket_provider` | `string` or `null` | Who sells the tickets ticket_url links to (Ticketmaster, Eventbrite), as Facebook names it; null when none. |
| `platform_specific.facebook.price_text` | `string` or `null` | The ticket price or range as Facebook shows it ("$25 – $40", "Free"); null when none is shown. |
| `platform_specific.facebook.date_text` | `string` or `null` | When it happens, as Facebook shows it, in the event's own time zone ("Sun, Nov 8 at 3:00 PM EST and 7 more", "Sat, Nov 21 - Nov 22", "Happening now"): on a recurring event its next date, where start_at is its first. Display text in the viewer's language; null when not shown. |
| `platform_specific.facebook.frequency` | `string` or `null` | How often it repeats, as Facebook names it, lowercased (single for a one-off event); null when not shown. |
| `platform_specific.facebook.occurrence_count` | `integer` or `null` | Dates of its recurring series (the parent's child events); 0 for a single event. |
| `platform_specific.facebook.city_id` | `string` or `null` | ID of the city Facebook files it under (its city Page, the number in facebook.com/events/explore/\<city>/\<id>/, which lists that city's events); place.city is the city's name. Null when not shown. |
| `platform_specific.facebook.metrics` | `object` | Facebook's own counts at fetch time; null = hidden or not exposed, 0 = zero. |
| `platform_specific.facebook.metrics.interested_count` | `integer` or `null` | People who marked themselves interested (not going), as Facebook counts them. |
| `platform_specific.facebook.metrics.response_count` | `integer` or `null` | People who responded going or interested, together, as Facebook counts them. |
| `approximate_fields` | `string[]` | JSON paths of values rounded by the platform or parsed from display text ("7.3K interested": platform_specific.facebook.metrics.interested_count). \[\] when all exact. |
| `unknown_fields` | `string[]` | JSON paths of lists whose \[\] means unknown rather than none (a source that cannot see them); null already means unknown for every other field. \[\] when every list is known. |

## Item errors

Besides the [request-level errors](https://socialtap.dev/docs/errors/index.md) every endpoint can return, event endpoints return:

| Code | HTTP | Retry | Meaning | What to do |
| --- | --- | --- | --- | --- |
| `not_found` | 404 | No | The item does not exist or was deleted. On GET /v1/requests/{id}/response: the response was not kept (details.reason says why). | Check the link or ID. Do not retry. |
| `private_or_unavailable` | 403 | No | The item exists but is not public: it is private, age- or region-restricted, or needs a login to view. It shares 403 with forbidden (which is about the key), so branch on the code. | Only public items can be fetched. Do not retry. |

---

[HTML version](https://socialtap.dev/resources/event/) · [Docs index for AI agents](https://socialtap.dev/llms.txt) · [All docs in one file](https://socialtap.dev/llms-full.txt)