> For the complete documentation index, see [llms.txt](https://support.pears.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.pears.io/plan/community-events/event-list-endpoint.md).

# Event List Endpoint

The PEARS Event List Endpoint provides programmatic access to an organization's published community events. Use it to display events on external websites, sync with other systems, or build custom integrations.

## Endpoint URL

```
https://pears.io/events/<org_slug>/events-api/
```

Replace `<org_slug>` with your organization's public identifier.

{% hint style="info" %}
**TIP:** Contact PEARS support if you don't know your organization's public slug.
{% endhint %}

## Pagination

Results are paginated, returning 20 items per page by default.

| Parameter   | Description                              |
| ----------- | ---------------------------------------- |
| `page`      | Page number to retrieve                  |
| `page_size` | Number of results per page (default: 20) |

**Example:**

```
https://pears.io/events/<org_slug>/events-api/?page=2&page_size=10
```

The paginated response includes the following metadata fields:

| Field              | Type           | Description                         |
| ------------------ | -------------- | ----------------------------------- |
| `next`             | String or null | URL of the next page of results     |
| `previous`         | String or null | URL of the previous page of results |
| `count`            | Integer        | Total number of matching results    |
| `num_pages`        | Integer        | Total pages available               |
| `page_size`        | Integer        | Results per page                    |
| `current_page_num` | Integer        | The current page number             |

## Ordering

Use the `ordering` parameter to sort results. Prefix a field name with a hyphen (`-`) to reverse the sort order.

Available fields:

* `title`
* `start_date`
* `created_at`
* `modified_at`

**Example:**

```
?ordering=-start_date
```

## Search

Use the `q` parameter to filter events by title.

**Example:**

```
?q=agriculture
```

## Filtering

Narrow results using one or more of the following filter parameters.

| Parameter    | Description                                                |
| ------------ | ---------------------------------------------------------- |
| `unit`       | Unit identifier                                            |
| `has_fee`    | Boolean indicating whether the event has a fee             |
| `zip_code`   | Filter by location ZIP code                                |
| `is_virtual` | Boolean for virtual (`true`) or in-person (`false`) events |
| `max_range`  | Maximum distance range from the ZIP code                   |

**Example:**

```
?unit=1&has_fee=true&zip_code=66502&is_virtual=false&max_range=50
```

## Response Fields

Each event object in the `results` array includes the following fields:

| Field                      | Type                      | Description                               |
| -------------------------- | ------------------------- | ----------------------------------------- |
| `id`                       | Integer                   | Event's unique identifier                 |
| `title`                    | String                    | Event name                                |
| `summary`                  | String                    | Brief event description                   |
| `event_image_upload`       | Integer                   | Unique image identifier                   |
| `event_image_download_url` | String                    | URL for downloading the event image       |
| `start_date`               | ISO 8601 DateTime         | Event start timestamp                     |
| `end_date`                 | ISO 8601 DateTime or null | Event end timestamp                       |
| `site_display`             | String                    | Event location name                       |
| `is_published`             | Boolean                   | Publication status                        |
| `is_in_person`             | Boolean                   | Whether in-person attendance is available |
| `is_virtual`               | Boolean                   | Whether virtual attendance is available   |
| `created_at`               | ISO 8601 DateTime         | Event creation timestamp                  |
| `modified_at`              | ISO 8601 DateTime         | Last modification timestamp               |
| `confirmation_message`     | String (HTML)             | Registration confirmation text            |
| `payment_instructions`     | String (HTML) or null     | Fee payment details                       |
| `has_fee`                  | Boolean                   | Whether the event charges fees            |
| `time_zone`                | String                    | Event timezone designation                |
| `display_name`             | String                    | Formatted event title                     |

{% hint style="warning" %}
**NOTE:** Only published events are returned by this endpoint.
{% endhint %}

## Example Response

A successful request returns a JSON object with pagination metadata and a `results` array of event objects.

```json
{
  "default_ordering": "",
  "ordering": "",
  "next": null,
  "previous": null,
  "count": 3,
  "num_pages": 1,
  "page_size": 20,
  "current_page_num": 1,
  "results": [
    {
      "id": 1,
      "title": "The Art and Science of Agricultural Technology (Symposium)",
      "summary": "Agricultural Technology stands as a pillar in our quest for advancement and understanding.",
      "event_image_upload": 428743,
      "event_image_download_url": "http://localhost:8000/uploads/download/428743/",
      "start_date": "2024-04-23T00:00:00-05:00",
      "end_date": null,
      "site_display": "4-H",
      "is_published": true,
      "is_in_person": true,
      "is_virtual": true,
      "created_at": "2024-03-11T20:44:40.225542-05:00",
      "modified_at": "2024-04-03T08:59:16.416519-05:00",
      "confirmation_message": "<p>Thank you for registering...</p>",
      "payment_instructions": null,
      "has_fee": false,
      "time_zone": "US/Central",
      "display_name": "The Art And Science Of Agricultural Technology (Symposium)"
    }
  ]
}
```

## Support

If you need help using this endpoint, contact PEARS support:

* Email: <support@pears.io>
* Phone: (785) 789-3199
* Hours: Monday–Friday, 8am–5pm CST


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://support.pears.io/plan/community-events/event-list-endpoint.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.