> ## Documentation Index
> Fetch the complete documentation index at: https://getanyapi.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Facebook Events

> Sell facebook.events on AnyAPI: the request your endpoint receives, the response it must return, and what the real-request check judges.

List public Facebook events for a city or place by its events-page URL (event name, date, venue, and attendance) as normalized JSON.

This page is the seller-facing summary of one catalog API, `facebook.events`. The transport rules that apply to every API a seller serves - signed requests, the response envelope, timeouts, and body limits - are on [the operator endpoint contract](https://getanyapi.com/docs/sell/operator-endpoint-contract.md).

## The price you compete with

AnyAPI publishes this API from **\$1.20 per 1,000 requests**. That is the price a buyer sees today, so it is the price your endpoint has to come in under to win traffic.

## The request your endpoint receives

| Field | Type | Required | What it means |
| - | - | - | - |
| `cursor` | string | no | Pagination cursor from a previous response to fetch the next page. |
| `time` | string | no | Timeframe filter for the returned events. Defaults to all time. One of: `today`, `this_week`, `next_week`. |
| `url` | string | yes | URL of a city's or place's Facebook Events page (e.g. [https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547](https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547)). |

> [accordion] Full input JSON Schema
>
> ```json theme={"dark"}
> {
>   "$schema": "https://json-schema.org/draft/2020-12/schema",
>   "$id": "https://getanyapi.com/schemas/facebook.events.input.json",
>   "example": {
>     "url": "https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547"
>   },
>   "title": "Facebook Events input",
>   "type": "object",
>   "additionalProperties": false,
>   "required": [
>     "url"
>   ],
>   "properties": {
>     "url": {
>       "type": "string",
>       "description": "URL of a city's or place's Facebook Events page (e.g. https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547)."
>     },
>     "time": {
>       "type": "string",
>       "enum": [
>         "today",
>         "this_week",
>         "next_week"
>       ],
>       "description": "Timeframe filter for the returned events. Defaults to all time."
>     },
>     "cursor": {
>       "type": "string",
>       "description": "Pagination cursor from a previous response to fetch the next page."
>     }
>   }
> }
> ```

## The response your endpoint must return

| Field | Type | Always present | What it means |
| - | - | - | - |
| `data` | null or object | yes | |
| `data.events` | array | yes | |
| `data.events[].coverImage` | string | no | Cover photo image URL of the event. |
| `data.events[].dayTimeSentence` | string | yes | |
| `data.events[].eventKind` | string | no | Event kind Facebook reports, e.g. "PUBLIC\_TYPE". |
| `data.events[].goingCount` | integer | yes | |
| `data.events[].id` | string | yes | |
| `data.events[].interestedCount` | integer | yes | |
| `data.events[].isHappeningNow` | boolean | no | Whether the event is happening right now. |
| `data.events[].isOnline` | boolean | yes | |
| `data.events[].isPast` | boolean | no | Whether the event has already finished. |
| `data.events[].name` | string | yes | |
| `data.events[].placeId` | string | no | Numeric Facebook id of the event's place, as a string. |
| `data.events[].placeName` | string | yes | |
| `data.events[].startTimestamp` | integer | yes | |
| `data.events[].url` | string | yes | |
| `data.nextCursor` | string or null | yes | Opaque cursor for the next page of events, or null when this lane has no more. Pass it back as cursor to continue. |
| `found` | boolean | yes | |

Extra fields are kept, missing declared fields fail.

> [accordion] Full output JSON Schema
>
> ```json theme={"dark"}
> {
>   "$schema": "https://json-schema.org/draft/2020-12/schema",
>   "$id": "https://getanyapi.com/schemas/facebook.events.output.json",
>   "title": "Facebook Events output",
>   "type": "object",
>   "additionalProperties": false,
>   "required": [
>     "found",
>     "data"
>   ],
>   "properties": {
>     "found": {
>       "type": "boolean"
>     },
>     "data": {
>       "oneOf": [
>         {
>           "type": "null"
>         },
>         {
>           "type": "object",
>           "additionalProperties": false,
>           "required": [
>             "nextCursor",
>             "events"
>           ],
>           "properties": {
>             "nextCursor": {
>               "type": [
>                 "string",
>                 "null"
>               ],
>               "description": "Opaque cursor for the next page of events, or null when this lane has no more. Pass it back as cursor to continue."
>             },
>             "events": {
>               "type": "array",
>               "items": {
>                 "type": "object",
>                 "required": [
>                   "id",
>                   "name",
>                   "url",
>                   "dayTimeSentence",
>                   "startTimestamp",
>                   "isOnline",
>                   "placeName",
>                   "interestedCount",
>                   "goingCount"
>                 ],
>                 "properties": {
>                   "id": {
>                     "x-anyapi-must-populate": true,
>                     "type": "string"
>                   },
>                   "name": {
>                     "x-anyapi-must-populate": true,
>                     "type": "string"
>                   },
>                   "url": {
>                     "x-anyapi-must-populate": true,
>                     "type": "string"
>                   },
>                   "dayTimeSentence": {
>                     "x-anyapi-must-populate": true,
>                     "type": "string"
>                   },
>                   "startTimestamp": {
>                     "x-anyapi-must-populate": true,
>                     "type": "integer"
>                   },
>                   "isOnline": {
>                     "type": "boolean"
>                   },
>                   "placeName": {
>                     "x-anyapi-must-populate": true,
>                     "type": "string"
>                   },
>                   "interestedCount": {
>                     "type": "integer"
>                   },
>                   "goingCount": {
>                     "type": "integer"
>                   },
>                   "coverImage": {
>                     "type": "string",
>                     "description": "Cover photo image URL of the event."
>                   },
>                   "placeId": {
>                     "type": "string",
>                     "description": "Numeric Facebook id of the event's place, as a string."
>                   },
>                   "eventKind": {
>                     "type": "string",
>                     "description": "Event kind Facebook reports, e.g. \"PUBLIC_TYPE\"."
>                   },
>                   "isPast": {
>                     "type": "boolean",
>                     "description": "Whether the event has already finished."
>                   },
>                   "isHappeningNow": {
>                     "type": "boolean",
>                     "description": "Whether the event is happening right now."
>                   }
>                 }
>               }
>             }
>           }
>         }
>       ]
>     }
>   }
> }
> ```

## Fields that must never come back empty

* `dayTimeSentence`
* `id`
* `name`
* `placeName`
* `startTimestamp`
* `url`

The repository marks these fields as ones every source must be able to fill. An empty value is only correct when the entity itself genuinely has nothing there.

## Not found, and how it differs from empty

When the entity does not exist, answer 2xx with the not-found shape:

```json theme={"dark"}
{
  "found": false,
  "data": null
}
```

An empty list is not a not-found: when the entity exists and has nothing to return, answer 2xx with `found: true` and an empty `events` array.

This output schema declares no `reason` field, so `found: false` is the whole not-found answer.

## Example request

```json theme={"dark"}
{
  "url": "https://www.facebook.com/events/explore/saint-petersburg-florida/111326725552547"
}
```

The registration tests send this example to your endpoint, with the API's other test inputs. After that, the real-request check sends your endpoint real past customer inputs, and an AI reviewer compares each answer with AnyAPI's own answer to the same input.

## Next

* [The operator endpoint contract](https://getanyapi.com/docs/sell/operator-endpoint-contract.md) for signing, budgets, and the real-request check.
* [Every API open to sellers](https://getanyapi.com/docs/sell/apis/index.md).
* Want to sell an API that is not on that list? Email [support@getanyapi.com](mailto:support@getanyapi.com).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.