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

# Events

> Retrieve the meetings, hearings, votes, and deadlines that documents and transcripts announce.

When a document or a transcript announces a meeting, a hearing, a vote, or a comment deadline, PolicyMate records it as an event. Events let you build a calendar of what is coming up across every jurisdiction you follow, from a committee hearing in a state capitol to a planning board session in a county office.

> [!WARNING]
>
> Every event is read by AI from the document or transcript that announces it, and most events have not been checked against their source. Each event carries a [`verification`](https://docs.policymate.io/verification) object that tells you whether it was checked, and the passage it was read from when PolicyMate located it. Before acting on an event, such as filing a comment, you should check its source.

## Retrieving Events

To retrieve a list of events, send a `GET` request to the `/events` endpoint. Events are returned in the order they start, soonest first. For example, the following request retrieves upcoming hearings and meetings in Maryland:

```http theme={null}
GET /api/v0/events?jurisdiction=US-MD&kind=meeting&starts_after=2026-11-06
```

To retrieve a single event, send a `GET` request to `/events/{id}`.

## Filtering Events

The `/events` endpoint accepts the [shared filters](https://docs.policymate.io/filtering.md), including the [recommendation filters](https://docs.policymate.io/filtering.md#recommendation-filters), along with the following query parameters:

| Parameter | Example | Description |
| - | - | - |
| `kind` | `meeting` | Only events of this kind. Accepts a list. |
| `starts_after`, `starts_before` | `2026-11-06` | Only events that may start within this range, as described in [Date Precision](#date-precision) |
| `document` | a document `id` | Only events announced by this document |
| `transcript` | a transcript `id` | Only events announced in this transcript |
| `sort` | `starts_at` | Also `updated_at`, or `relevance` when searching with `q`. Defaults to `starts_at`. |

The `q` parameter searches the event's name and description. An event's jurisdiction is the jurisdiction of the document or transcript that announces it.

## The Event Object

An event looks like the following. The values below are illustrative:

```json theme={null}
{
  "id": "71b0c3e2-5a4f-4e1d-9b8a-3c2d1e0f9a87",
  "type": "event",
  "kind": "meeting",
  "name": "Planning Board public hearing on ZTA 26-05",
  "description": "Public hearing on the zoning text amendment for data center uses in industrial zones.",
  "starts_at": "2026-11-20T18:30:00-05:00",
  "ends_at": null,
  "date_precision": "time",
  "counted_from_publication": null,
  "timezone": "America/New_York",
  "location": "County Office Building, Hearing Room 1",
  "is_recurring": false,
  "recurrence": null,
  "source": {
    "type": "document",
    "id": "c27a9e04-...",
    "title": "Notice of Public Hearing: Zoning Text Amendment for Data Center Uses",
    "publisher": { "id": "0f8e...", "name": "Fairview County Planning Board" }
  },
  "verification": {
    "status": "confirmed",
    "checked_at": "2026-10-29T04:05:30Z",
    "sources": [
      {
        "type": "document",
        "id": "c27a9e04-...",
        "publisher": "Fairview County Planning Board",
        "title": "Notice of Public Hearing: Zoning Text Amendment for Data Center Uses",
        "date": "2026-10-28",
        "url": "https://planning.fairviewcounty.example/...",
        "quote": "The Planning Board will hold a public hearing on November 20, 2026 at 6:30 p.m. in Hearing Room 1.",
        "starts_at_second": null
      }
    ]
  },
  "recommendations": [
    { "workspace": { "id": "3a9d...", "name": "Data centers" }, "importance": "medium" }
  ],
  "created_at": "2026-10-29T04:02:11Z",
  "updated_at": "2026-10-29T04:02:11Z"
}
```

An event's `kind` is one of `meeting`, `vote`, `deadline`, `consultation`, `conference`, `summit`, `webinar`, `workshop`, `press_conference`, or `other`.

When the source describes a recurring event, such as "every first Tuesday", `is_recurring` is `true` and `recurrence` holds that description in plain words. A recurring event is returned once, at its next known date, not as a series of occurrences.

The `source` attribute is the document or transcript that announces the event. Its `type` is `document` or `transcript`, and its `publisher` is `null` for transcripts. When several sources announce the same event, PolicyMate returns the event once, with the first source that announced it. Two announcements are only treated as the same event when they agree on its date, so recognising duplicates is a best effort rather than a guarantee.

### Postponed and Cancelled Events

PolicyMate does not track whether an event was postponed or cancelled. When a later document announces a new date, PolicyMate records it as a new event, and the original event keeps its date. Before relying on an event, especially one announced weeks earlier, you should look for newer events with a similar name.

The `recommendations` attribute lists the workspaces the event was recommended to, as described in [Recommendations on Records](https://docs.policymate.io/filtering.md#recommendations-on-records).

## Date Precision

Sources do not always give an exact date. A notice may say a hearing will take place "in December", or that comments are due "within 30 days". Rather than inventing a precise date, PolicyMate records how precisely the source dated the event in the `date_precision` attribute:

| Value | The source gave | `starts_at` holds |
| - | - | - |
| `time` | A date and a time | The exact time |
| `day` | A date | Midnight on that day |
| `week` | A week, such as "next week" | The first day of that week |
| `month` | A month, such as "in December" | The first day of that month |
| `year` | A year, such as "in 2027" | The first day of that year |
| `null` | Not recorded | A date PolicyMate read before it began recording precision. Treat it as approximate. |

You should display an event no more precisely than its `date_precision`. For example, an event with a `month` precision should read "December 2026", not "December 1, 2026", and a `day` precision never means the event starts at midnight.

When the source counts the date from its own publication, such as comments due "within 30 days", the `counted_from_publication` attribute holds that period as an ISO 8601 duration, such as `P30D`, and `starts_at` is the source's publication date plus that period. It is `null` when the source states the date itself.

### Filtering by Date

The `starts_after` and `starts_before` filters match every event that may start within the range. An event dated "in December" is treated as starting at some point in December, so a request for events starting after December 15 includes it. Dates you pass are read in each event's own timezone, so `starts_before=2026-12-15` includes events on December 15, wherever they take place.


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