Facebook City Events API

Open in ChatGPT Open in Claude Open in Gemini

Public events Facebook is suggesting for a city, from its Events Explore feed (e.g. https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547). time narrows the window to today, this week, or next week; without it Facebook returns whatever it has queued as upcoming, in whatever order it ranks them. Only the first, server-rendered page: host and description are not exposed on this listing (only on /v1/facebook/event). pagination.hasMore says whether Facebook has more; this endpoint returns no cursor to fetch them. Calls cost 1 credit each. A cache hit is free, and a failed or empty response is never charged.

Try it

Prefilled with the request that produced the example below. No key yet? Get a free key.

Request

GET/v1/facebook/city-events

Parameter	Type	Required	Description
url	string	yes	Explore URL ("facebook.com/events/explore/<city-slug>/<id>") or a bare "<city-slug>/<id>" pair
time	today \| this_week \| next_week	no	Narrow to Facebook's own window. Defaults to all upcoming.

Parameter

Type

Required

Description

url

string

yes

Explore URL ("facebook.com/events/explore/<city-slug>/<id>") or a bare "<city-slug>/<id>" pair

time

today | this_week | next_week

Narrow to Facebook's own window. Defaults to all upcoming.

Also accepts cache_max_age (a hit costs 0 credits) and include_raw (returns the untouched upstream payload under raw).

curl

curl "$API/v1/facebook/city-events?url=nyc%2F108424279189115&cache_max_age=7d" \
  -H "x-api-key: $KEY"

JavaScript

const query = new URLSearchParams({
  url: 'nyc/108424279189115',
  cache_max_age: '7d',
});

const response = await fetch(`${API}/v1/facebook/city-events?${query}`, {
  headers: { 'x-api-key': KEY },
});

const body = await response.json();
if (!body.success) throw new Error(body.error.code);

// 1 credit, 0 on a cache hit
console.log(body.data, body.meta.creditsCharged);

Python

import os, httpx

r = httpx.get(
    f"{os.environ['API']}/v1/facebook/city-events",
    params={
        "url": "nyc/108424279189115",
        "cache_max_age": "7d",
    },
    headers={"x-api-key": os.environ["KEY"]},
    timeout=30,
)

body = r.json()
if not body["success"]:
    raise RuntimeError(body["error"]["code"])

print(body["data"], body["meta"]["creditsCharged"])

Example response

Captured on 2026-10-21, with raw removed and lists cut to two items. A live call returns current data.

response

{
  "success": true,
  "data": {
    "items": [
      {
        "platform": "facebook",
        "id": "937082358964289",
        "name": "Starbucks Reserve® Sunrise Experience",
        "url": "https://www.facebook.com/events/937082358964289/",
        "description": null,
        "startsAt": "2026-10-24T10:00:00.000Z",
        "endsAt": null,
        "timeText": "Sat, Oct 24 at 6:00 AM EDT",
        "isOnline": false,
        "isCanceled": null,
        "isPast": false,
        "place": {
          "id": "1513257436828045",
          "name": "Empire State Building, New York City",
          "address": null,
          "latitude": null,
          "longitude": null
        },
        "hostId": null,
        "hostName": null,
        "hostUrl": null,
        "thumbnailUrl": "https://scontent-sin2-2.xx.fbcdn.net/v/t39.30808-6/655891148_1507509490736173_1808911119770123743_n.avif?stp=c0.275.1080.516a_dst-jpg_tt6&cstp=mx1080x516&ctp=s320x320&_nc_cat=103&ccb=1-7&_nc_sid=75d36f&_nc_ohc=xnrTzz4-B1QQ7kNvwGWRg5O&_nc_oc=AdqqLtCU7KzCCTYVzLDtKHB2dfOYGQ1BGJJm52cvKGrPtkGIwW0Cv-zisTf5O-J4V7k&_nc_zt=23&_nc_ht=scontent-sin2-2.xx&_nc_gid=djtUhs9rMgYvf0RG-7KNCA&_nc_ss=70289&oh=00_AQNYWj27Tuen7LRiAI_cw8k95DW9zMTr31bN5vknxxZt0w&oe=6ADDEAB8",
        "ticketPriceText": null,
        "interestedCount": 54,
        "fetchedAt": "2026-10-21T01:51:39.481Z"
      },
      {
        "platform": "facebook",
        "id": "968251775614943",
        "name": "The Phil Collins Story",
        "url": "https://www.facebook.com/events/968251775614943/",
        "description": null,
        "startsAt": "2026-10-31T00:00:00.000Z",
        "endsAt": null,
        "timeText": "Fri, Oct 30 at 8:00 PM EDT",
        "isOnline": false,
        "isCanceled": null,
        "isPast": false,
        "place": {
          "id": "1527039652788991",
          "name": "St. George Theatre",
          "address": null,
          "latitude": null,
          "longitude": null
        },
        "hostId": null,
        "hostName": null,
        "hostUrl": null,
        "thumbnailUrl": "https://scontent-sin11-2.xx.fbcdn.net/v/t39.30808-6/670633524_1423489739819579_4577715628917311141_n.avif?stp=c0.58.2048.977a_dst-jpg_tt6&cstp=mx2048x977&ctp=s320x320&_nc_cat=108&ccb=1-7&_nc_sid=75d36f&_nc_ohc=pluylbtqdW4Q7kNvwH_JEq3&_nc_oc=AdqB3GHgTFo2Yw2r9Vj82qHksLSNPTD-HU9ItXe5J_y5BldjyXNafiWvv-eknXTZTdw&_nc_zt=23&_nc_ht=scontent-sin11-2.xx&_nc_gid=djtUhs9rMgYvf0RG-7KNCA&_nc_ss=70289&oh=00_AQMBg26FxWN-VCJ2qRCrkUg2AxJ4W6DAVw4gwIM8ogijAw&oe=6ADDE518",
        "ticketPriceText": null,
        "interestedCount": 1656,
        "fetchedAt": "2026-10-21T01:51:39.481Z"
      }
    ]
  },
  "pagination": {
    "cursor": null,
    "hasMore": true,
    "count": 12
  },
  "meta": {
    "platform": "facebook",
    "endpoint": "facebook.cityEvents",
    "creditsCharged": 1,
    "cached": false,
    "cacheAgeSeconds": null,
    "durationMs": 1644,
    "requestId": "req_tuw0ab3gcog5kd410bbs"
  }
}

Returns

Returns a list of object in data.items.

Fields

Field	Type	Present	Description
platform	"facebook"	always
id	string	always
name	string \| null	always
url	string	always
description	string \| null	always
startsAt	string \| null	always	ISO 8601, UTC.
endsAt	string \| null	always	ISO 8601, UTC. Null when the event has no end time.
timeText	string \| null	always	Facebook's own rendering of the time, e.g. "Sat, Sep 5 at 3:00 PM MDT". It carries the event's LOCAL timezone, which the epoch timestamps do not.
isOnline	boolean \| null	always
isCanceled	boolean \| null	always
isPast	boolean \| null	always
place	object \| null	always
place.id	string \| null	always
place.name	string \| null	always
place.address	string \| null	always
place.latitude	number \| null	always
place.longitude	number \| null	always
hostId	string \| null	always
hostName	string \| null	always
hostUrl	string \| null	always
thumbnailUrl	string \| null	always
ticketPriceText	string \| null	always
interestedCount	number \| null	always	People who marked the event Interested or Going. In list results above a thousand, Facebook's rounded figure ("1.2K").
fetchedAt	string	always

Field

Type

Present

Description

platform

"facebook"

always

string

always

name

string | null

always

url

string

always

description

string | null

always

startsAt

string | null

always

ISO 8601, UTC.

endsAt

string | null

always

ISO 8601, UTC. Null when the event has no end time.

timeText

string | null

always

Facebook's own rendering of the time, e.g. "Sat, Sep 5 at 3:00 PM MDT". It carries the event's LOCAL timezone, which the epoch timestamps do not.

isOnline

boolean | null

always

isCanceled

boolean | null

always

isPast

boolean | null

always

place

object | null

always

place.id

string | null

always

place.name

string | null

always

place.address

string | null

always

place.latitude

number | null

always

place.longitude

number | null

always

hostId

string | null

always

hostName

string | null

always

hostUrl

string | null

always

thumbnailUrl

string | null

always

ticketPriceText

string | null

always

interestedCount

number | null

always

People who marked the event Interested or Going. In list results above a thousand, Facebook's rounded figure ("1.2K").

fetchedAt

string

always

Cost and behaviour

Credits

1 per live request, 0 on a cache hit

Cacheable

yes: cache_max_age accepts a cached copy

Batchable

yes: usable as a target in POST /v1/jobs/batch

Subscribable

Other Facebook endpoints

/v1/facebook/ad-library/ad Ad details
/v1/facebook/ad-library/ad-transcript Ad video transcript
/v1/facebook/ad-library/advertisers Find advertisers running ads
/v1/facebook/ad-library/page-ads All ads for one advertiser
/v1/facebook/ad-library/search Search the Meta Ad Library
/v1/facebook/comment-replies Replies to a comment
/v1/facebook/event Event details
/v1/facebook/events/search Search public events

All Facebook endpoints The unified schema

Contents

Site

Facebook City Events API

Try it

Request

Example response

Returns

Cost and behaviour

Other Facebook endpoints