# List agenda items

> Agenda items, newest meeting first and in agenda order within a meeting, each with its plain-words summary where one passed its check, and its business topics. Billed as one records request a page. Filters: jurisdiction, region, country, topic, from, to, since, meeting.

`GET /v1/agenda-items`

Agenda items, newest meeting first and in agenda order within a meeting, each with its plain-words summary where one passed its check, and its business topics. Billed as one records request a page. Filters: jurisdiction, region, country, topic, from, to, since, meeting.

Authentication: `Authorization: Bearer <key>`, an `htd_test_` (sandbox) or `htd_live_` (live) key.

```bash
curl "https://data.heytownhall.com/v1/agenda-items" \
  -H "Authorization: Bearer $HTD_KEY"
```

## Parameters

| Name | In | Required | Description |
| --- | --- | --- | --- |
| `jurisdiction` | query | no | A jurisdiction id. |
| `region` | query | no | A two-letter province or state code. |
| `country` | query | no | CA or US. |
| `topic` | query | no | A business topic id (GET /v1/topics lists the tags given). |
| `from` | query | no | On or after this date (YYYY-MM-DD). |
| `to` | query | no | On or before this date (YYYY-MM-DD). |
| `since` | query | no | Records read at or after this instant: what is new since your last read. |
| `meeting` | query | no | A meeting id. |
| `limit` | query | no | Results a page, 1 to 100. Default 25. |
| `cursor` | query | no | next_cursor from the previous page. |

## Fields of each result

| Field | Type | Description |
| --- | --- | --- |
| `id` | string | `{meeting_id}-{position}`. |
| `meeting_id` | string |  |
| `position` | number |  |
| `jurisdiction_id` | string |  |
| `country` | string or null |  |
| `region` | string or null |  |
| `meeting_date` | string | YYYY-MM-DD. |
| `depth` | number or null |  |
| `number` | string or null |  |
| `title` | string |  |
| `recommendation` | string or null |  |
| `video_seconds` | number or null | Where the item starts in the meeting video, in seconds. |
| `plain_summary` | string or null | The item in plain words, kept only when checked against its source. |
| `why_it_matters` | string or null |  |
| `report_url` | string or null |  |
| `topics` | array of string | Business topics; empty means not yet tagged. |
| `source_url` | string or null | The page, document, video or platform the record was read from. |
| `read_at` | string or null | When it was read. |

## Answers

| Status | Meaning |
| --- | --- |
| `200` | A page. |
| `400` | invalid_request: a parameter is missing or not valid; `param` names it. |
| `401` | unauthorized: no key, or not a valid one. |
| `402` | billing_required (a live key without a payment method, or paused for an unpaid invoice) or spend_cap_reached. |
| `429` | rate_limited: past the key's requests per minute. Retry-After says when to try again. |
| `503` | upstream_unavailable: the data could not be read. Not an empty answer; try again. |