Schemas

Event

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.

Schema

Single-item endpoints return this object as data; list endpoints return an array of them as data with a page object. The standard meta comes with every response.

platformstring

Platform ID (facebook, …).

idstring

Platform-native event ID (string; Facebook's numeric event ID).

urlstring uri

Canonical event page URL (https://www.facebook.com/events/<id>/).

namestring

The event's name as its page shows it.

descriptionstringnullable

Its description as plain text; null when it has none.

statusstring

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.

One ofscheduledongoingendedcanceledunknown

start_atstring date-timenullable

When it starts, RFC 3339 UTC; null only when the platform shows no start.

end_atstring date-timenullable

When it ends, RFC 3339 UTC; null when its hosts set no end or the platform does not show it.

time_zonestringnullable

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_minutesintegernullable

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_onlinebooleannullable

Held online (a stream or video call) rather than at a venue.

placeobjectnullable

Where it is held; null for an online event with no venue or when not shown.

Show 8 child fields

idstringnullable

The place's ID as the platform's place endpoints key it (place.id); null for a venue given as free text.

namestringnullable

The place's name as shown (a venue's name, or the text its host typed).

urlstring urinullable

The place's page URL; null for a venue given as free text.

addressstringnullable

Address as the platform shows it (one line, not normalized).

citystringnullable

City or locality, as shown.

country_codestringnullable

ISO 3166-1 alpha-2 country of the place.

latitudenumbernullable

WGS 84 latitude in degrees; null when the platform shows no coordinates (set together with longitude).

longitudenumbernullable

WGS 84 longitude in degrees; null when the platform shows no coordinates (set together with latitude).

hostsobject[]

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).

Show 6 child fields

idstringnullable

Platform-native account ID; null when only the handle is known.

usernamestringnullable

Handle without the @; null when the account has none.

display_namestringnullable

Display name shown on the profile.

urlstring urinullable

Canonical profile URL.

avatar_urlstring urinullable

Profile picture URL. Platform CDN URLs can expire within hours.

is_verifiedbooleannullable

Platform verification badge; null where the platform has no badge.

cover_urlstring urinullable

The event's cover image (a video cover's poster frame); null when it has none. Platform CDN URLs can expire within days.

categoriesstring[]

Categories the platform files it under, as shown (not normalized), the main one first; [] when none.

ticket_urlstring urinullable

Where to buy tickets or register, as the platform links it; null when none is linked.

parent_idstringnullable

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_idstringnullable

ID of the community it belongs to (the Facebook group it was created in; community.id); null when none.

metricsobject

Counts at fetch time; null = hidden or not exposed, 0 = zero.

Show 1 child field

attendee_countintegernullable

People who said they are going (after the event: who went), as the platform counts them; null when not shown.

platform_specificobject

Fields only this platform has, under its ID (platform_specific.<platform>); each null when unknown.

Show 1 child field

facebookobjectnullable

A Facebook event's own fields.

Show 7 child fields

ticket_providerstringnullable

Who sells the tickets ticket_url links to (Ticketmaster, Eventbrite), as Facebook names it; null when none.

price_textstringnullable

The ticket price or range as Facebook shows it ("$25 – $40", "Free"); null when none is shown.

date_textstringnullable

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.

frequencystringnullable

How often it repeats, as Facebook names it, lowercased (single for a one-off event); null when not shown.

occurrence_countintegernullable

Dates of its recurring series (the parent's child events); 0 for a single event.

city_idstringnullable

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.

metricsobject

Facebook's own counts at fetch time; null = hidden or not exposed, 0 = zero.

Show 2 child fields

interested_countintegernullable

People who marked themselves interested (not going), as Facebook counts them.

response_countintegernullable

People who responded going or interested, together, as Facebook counts them.

approximate_fieldsstring[]

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_fieldsstring[]

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 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.

Example (Facebook Events)

{
  "data": {
    "approximate_fields": [],
    "categories": [
      "Music & audio"
    ],
    "community_id": null,
    "cover_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-6/701643646_1454949970006889_5222368129042891587_n.avif?stp=dst-jpg_tt6&cstp=mx2048x1152&ctp=s2048x1152&_nc_cat=105&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=23&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED…",
    "description": "Arch Enemy & The Black Dahlia Murder will be performing at Jannus Live on Sunday, October 18th. This event is All Ages. Doors open at 5:00 PM, Show starts at 6:00 PM. All support acts are subject to change without notice. This event is rain or shine.\n\nSale Dates and Times:\n\nPubli…",
    "end_at": null,
    "hosts": [
      {
        "avatar_url": "https://scontent-atl3-2.xx.fbcdn.net/v/t39.30808-1/703461784_1493244248837311_492679311377568321_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx1080x1080&ctp=s74x74&_nc_cat=104&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-2.xx&_nc_gid=SCRUBBED&_…",
        "display_name": "Thrown Into Exile",
        "id": "100044552494354",
        "is_verified": true,
        "url": "https://www.facebook.com/ThrownIntoExile",
        "username": "ThrownIntoExile"
      },
      {
        "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/481358765_1074963661337894_2872436054536647170_n.jpg?stp=cp0_dst-jpg_tt6&cstp=mx1024x1024&ctp=s74x74&_nc_cat=103&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&…",
        "display_name": "No Clubs",
        "id": "100064728099080",
        "is_verified": false,
        "url": "https://www.facebook.com/Noclubsproductions",
        "username": "Noclubsproductions"
      },
      {
        "avatar_url": "https://scontent-atl3-1.xx.fbcdn.net/v/t39.30808-1/302197946_452479626918288_252645739401521140_n.png?stp=cp0_dst-png&cstp=mx200x200&ctp=s74x74&_nc_cat=106&ccb=SCRUBBED&_nc_sid=SCRUBBED&_nc_ohc=SCRUBBED&_nc_oc=SCRUBBED&_nc_zt=24&_nc_ht=scontent-atl3-1.xx&_nc_gid=SCRUBBED&_nc_ss=7…",
        "display_name": "Jannus Live",
        "id": "100064687631616",
        "is_verified": false,
        "url": "https://www.facebook.com/jannuslive",
        "username": "jannuslive"
      }
    ],
    "id": "2513378022457980",
    "is_online": false,
    "metrics": {
      "attendee_count": 52
    },
    "name": "Arch Enemy & The Black Dahlia Murder: Wrath Across North America 2026",
    "parent_id": null,
    "place": {
      "address": "201 Central Ave, St Petersburg, FL 33701-3325, United States",
      "city": "Saint Petersburg, Florida",
      "country_code": null,
      "id": null,
      "latitude": 27.771757351792,
      "longitude": -82.636019393897,
      "name": "Jannus Live",
      "url": null
    },
    "platform": "facebook",
    "platform_specific": {
      "facebook": {
        "city_id": "111326725552547",
        "date_text": "Sunday, October 18, 2026 at 5:00 PM EDT",
        "frequency": "single",
        "metrics": {
          "interested_count": 355,
          "response_count": 407
        },
        "occurrence_count": 0,
        "price_text": null,
        "ticket_provider": null
      }
    },
    "start_at": "2026-10-18T21:00:00Z",
    "status": "ended",
    "ticket_url": null,
    "time_zone": null,
    "unknown_fields": [],
    "url": "https://www.facebook.com/events/2513378022457980/",
    "utc_offset_minutes": -240
  },
  "meta": {
    "request_id": "req_3f9c2a7d1e8b4c6a9f0e2d4b6a8c0e1f",
    "platform": "facebook",
    "source": "api",
    "is_cached": false,
    "credits_charged": 1,
    "latency_ms": 866,
    "fetched_at": "2026-10-25T12:00:00Z",
    "input": {
      "kind": "event",
      "id": "2513378022457980",
      "url": "https://www.facebook.com/events/2513378022457980/"
    },
    "credits_remaining": 9999,
    "client_request_id": null,
    "warnings": []
  }
}

Long arrays and strings are shortened for display.