---
title: "Retrieve Events"
method: GET
path: "/v1/events"
tags: ["Events"]
---

# Retrieve Events

`GET /v1/events`

## Request

- Base URL: `https://api.exhibitday.com`
- URL: `https://api.exhibitday.com/v1/events`
- Auth: one of:
  - API key in header `api_key`
  - API key in query parameter `api_key`

This method retrieves events in your workspace based on various filter criteria. The filter parameters for this method work in conjunction on an “AND-basis”. For example, if you pass in the value “2026-01-30” for filter_by_start_date_greater_than_or_equal_to and the value “1” for filter_by_event_format_id, you’ll get back all the events in your workspace that have their start date greater than or equal to Jan 30, 2026 AND have their format set to In-Person. Also, you can only pass in one value for each filter parameter; this means that you can’t pass in “1, 2” as the value for the filter_by_event_star_rating filter parameter expecting to get back all the events that have a 1-star or a 2-star rating.

filter_by_custom_event_field__custom_NNNNNN (replace NNNNNN with the id): This is a special filter that lets you filter down your events based on a value of a Custom Text field or a Custom Dropdown field under the Event Information tab, Event Booth tab, or the Special Event tab. To use this filter, you’ll need the field name for the custom text field or custom dropdown field. You can obtain a list of field names for custom event fields in your workspace from the following endpoint: /v1/references/event_custom_fields. For example, if you have configured a custom dropdown field called “Region” under the Event information tab, and its field name is “custom_123456” and you would like to filter your events to include only ones that have “Northeast” selected for that custom dropdown field, pass in “filter_by_custom_event_field__custom_123456” as the parameter name and “Northeast” as its parameter value. Note: You can only filter down based on one custom event field (and it has to be either a custom text field or a custom dropdown field). A request with more than one custom-field filter is rejected with an error. If your workspace has no custom text field or custom dropdown field with the id in the parameter name, the request is rejected with an error.

Documentation: https://api.exhibitday.com/Help/V1?epf=1#get-v1-events

## Query parameters

- `filter_by_event_name_contains_text` string
- `filter_by_start_date_greater_than_or_equal_to` string, date
- `filter_by_start_date_smaller_than_or_equal_to` string, date
- `filter_by_end_date_greater_than_or_equal_to` string, date
- `filter_by_end_date_smaller_than_or_equal_to` string, date
- `filter_by_event_participation_type_id` integer
- `filter_by_event_format_id` integer
- `filter_by_event_star_rating` number
- `filter_by_event_tag` string
- `filter_by_integration_metadata_field_1` string
- `filter_by_integration_metadata_field_2` string
- `filter_by_integration_metadata_field_3` string
- `filter_by_integration_metadata_field_4` string
- `filter_by_integration_metadata_field_5` string
- `hydrate_tasks` boolean
- `hydrate_task_sections_list` boolean
- `hydrate_event_misc_expenses_and_credits` boolean
- `hydrate_custom_fields` boolean
- `event_id` integer
- `filter_by_event_start_date_category` string
- `filter_by_custom_field_value_setting_id` integer
- `filter_by_custom_field_value_setting_value` string
- `$result_sort` string
- `$return_event_lites` boolean
- `filter_by_last_update_timestamp_greater_than_or_equal_to` string
- `$limit` integer
- `$offset` integer
- `$result_format` string
- `$on_error_return_empty_result` boolean

## Headers

- `If-None-Match` string

## Response `200`

OK

- union
  - EventsList, nullable
    - `records_found` integer
    - `total_records` integer
    - `has_more` boolean
    - `list_type` string, nullable
    - `list_data` Event[], nullable
      - `id` integer
      - `exhibitday_url` string, nullable
      - `name` string, nullable
      - `start_date` string, nullable
      - `end_date` string, nullable
      - `participation_type_id` integer
      - `participation_type` string, nullable
      - `format_id` integer
      - `format` string, nullable
      - `star_rating` integer
      - `tags` string[], nullable
      - `website_url` string, nullable
      - `venue_name` string, nullable
      - `venue_address` string, nullable
      - `venue_location_display_name` string, nullable
      - `venue_address_latitude` string, nullable
      - `venue_address_longitude` string, nullable
      - `booth_size` string, nullable
      - `booth_number` string, nullable
      - `booth_reservation_status_id` integer
      - `booth_reservation_status` string, nullable
      - `booth_reserve_by_date` string, nullable
      - `booth_date_reserved` string, nullable
      - `budget_booth_reservation` number
      - `budget_booth_services` number
      - `budget_attendee_registrations` number
      - `budget_travel` number
      - `budget_giveaways` number
      - `budget_shipments` number
      - `budget_event_activities` number
      - `budget_misc_expenses` number
      - `budget_sponsorships` number
      - `total_sum_event_budgets` number
      - `cost_booth_reservation` number
      - `cost_booth_services` number
      - `cost_attendee_registrations` number
      - `cost_travel_reservations` number
      - `cost_giveaways` number
      - `cost_shipments` number
      - `cost_event_activities` number
      - `cost_misc_expenses` number
      - `cost_sponsorships` number
      - `total_sum_event_costs` number
      - `event_notes` string, nullable
      - `booth_notes` string, nullable
      - `budget_notes` string, nullable
      - `roi_notes` string, nullable
      - `roi_num_leads` integer
      - `roi_num_impressions_booth` integer
      - `roi_num_impressions_sponsorships` integer
      - `roi_num_impressions_media` integer
      - `roi_num_meetings_existing_customers` integer
      - `roi_num_meetings_new_customers` integer
      - `roi_amount_actual_sales` number
      - `roi_amount_potential_sales` number
      - `event_created_timestamp` string, date-time, nullable
      - `event_last_update_timestamp` string, date-time
      - `event_created_by` AspNetUserReferenced, nullable
        - `id` string, nullable
        - `first_name` string, nullable
        - `last_name` string, nullable
        - `email` string, nullable
      - `custom_fields` CustomEventFieldReferenced[], nullable
        - `label` string, nullable
        - `value` string, nullable
        - `notes` string, nullable
        - `field_name` string, nullable
        - `field_type` string, nullable
        - `field_event_tab` string, nullable
      - `task_sections` TaskSectionReferenced[], nullable
        - `id` integer
        - `name` string, nullable
        - `display_rank` integer
      - `tasks` TaskReferenced[], nullable
        - `id` integer
        - `exhibitday_url` string, nullable
        - `event_task_section_id` integer, nullable
        - `event_task_section` string, nullable
        - `display_rank` integer
        - `name` string, nullable
        - `due_date` string, nullable
        - `assignee` AspNetUserReferenced, nullable
          - `id` string, nullable
          - `first_name` string, nullable
          - `last_name` string, nullable
          - `email` string, nullable
        - `is_completed` boolean
        - `task_completed_timestamp` string, date-time, nullable
        - `task_created_timestamp` string, date-time
        - `task_last_update_timestamp` string, date-time
      - `misc_expenses_credits` EventMiscExpenseCreditReferenced[], nullable
        - `id` integer
        - `exhibitday_url` string, nullable
        - `description` string, nullable
        - `is_credit` boolean
        - `amount` number
        - `amount_cost_center_breakdown` CostCenterBreakdown[], nullable
          - `cost_center_id` integer, nullable
          - `cost_center` string, nullable
          - `charge` number
        - `notes` string, nullable
        - `payment_due_date` string, nullable
        - `payment_status` PaymentStatusReferenced, nullable
          - `id` integer
          - `name` string, nullable
        - `next_partial_payment_due_date` string, nullable
        - `payment_notes` string, nullable
        - `event_misc_expense_credit_created_timestamp` string, date-time
        - `event_misc_expense_credit_last_update_timestamp` string, date-time
      - `integration_metadata_field_1` string, nullable
      - `integration_metadata_field_2` string, nullable
      - `integration_metadata_field_3` string, nullable
      - `integration_metadata_field_4` string, nullable
      - `integration_metadata_field_5` string, nullable
  - EventLitesList, nullable
    - `records_found` integer
    - `total_records` integer
    - `has_more` boolean
    - `list_type` string, nullable
    - `list_data` EventLite[], nullable
      - `id` integer
      - `exhibitday_url` string, nullable
      - `name` string, nullable
      - `start_date` string, nullable
      - `end_date` string, nullable
      - `participation_type_id` integer
      - `participation_type` string, nullable
      - `format_id` integer
      - `format` string, nullable
      - `star_rating` integer
      - `event_created_timestamp` string, date-time, nullable
      - `event_last_update_timestamp` string, date-time
      - `integration_metadata_field_1` string, nullable
      - `integration_metadata_field_2` string, nullable
      - `integration_metadata_field_3` string, nullable
      - `integration_metadata_field_4` string, nullable
      - `integration_metadata_field_5` string, nullable

## Other responses

- `304`: Not Modified: If-None-Match named the current ETag, so there is no body.
- `400`: Bad Request: a missing or invalid parameter, or a change that is not allowed (error_code says which).
- `401`: Unauthorized: the api_key is missing or invalid, or API access is not enabled for the workspace.
- `404`: Not Found: no object with that id in your workspace, or an unknown URL or method.
- `429`: Too Many Requests: the rate limit was exceeded.
- `500`: Unexpected Internal Error.

---

[API](https://skmtc.dev/exhibitday/apis/exhibitday-api.md) · [All operations](https://skmtc.dev/exhibitday/apis/exhibitday-api/llms.txt) · [OpenAPI document](https://skmtc.dev/exhibitday/apis/exhibitday-api/revisions/a35e95422b0a?raw)