# Meetings > Meetings, agenda items, meeting documents, motions, recorded votes, attendance, recordings and transcripts. Councils, boards and committees, as their own meeting platforms and minutes publish them. A meeting is the parent of the records below it: pass its id as `meeting` to read only that meeting's agenda items, documents, motions, votes, attendance or recordings. Motions, votes and attendance are read from the minutes as printed. A vote is never derived. ## Meetings ### `GET /v1/meetings` **List meetings.** Meetings of councils, boards and committees, newest first. `topic` keeps meetings with an agenda item, motion, document or recording tagged with it. Billed as one records request a page. Filters: jurisdiction, region, country, kind, topic, from, to, since. [Reference and playground for list meetings](https://data.heytownhall.com/docs/reference/meetings/get-v1-meetings) | Parameter | What it takes | | -------------- | ------------------------------------------------------------------------- | | `jurisdiction` | A jurisdiction id. | | `region` | A two-letter province or state code. | | `country` | CA or US. | | `kind` | council, committee_of_the_whole, public_hearing, board, committee, other. | | `topic` | A business topic id (GET /v1/topics lists the tags given). | | `from` | On or after this date (YYYY-MM-DD). | | `to` | On or before this date (YYYY-MM-DD). | | `since` | Records read at or after this instant: what is new since your last read. | Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)). | Field | Type | What it holds | | ----------------- | --------------- | ------------------------------------------------------------------------- | | `id` | string | | | `jurisdiction_id` | string | | | `country` | string or null | | | `region` | string or null | | | `title` | string | | | `kind` | string or null | council, committee_of_the_whole, public_hearing, board, committee, other. | | `closed` | boolean or null | | | `cancelled` | boolean or null | | | `meeting_date` | string | YYYY-MM-DD. | | `starts_at` | string or null | ISO 8601 instant, UTC. | | `time_zone` | string or null | | | `location` | string or null | | | `platform` | string or null | The meeting vendor it was read from. | | `organ_id` | string or null | | | `organ_name` | string or null | | | `organ_kind` | string or null | | | `agenda_seen_at` | string or null | When the agenda first appeared. | | `items_read_at` | string or null | ISO 8601 instant, UTC. | | `minutes_read_at` | string or null | ISO 8601 instant, UTC. | | `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. | ### `GET /v1/meetings/{id}` **Retrieve a meeting.** One meeting with its agenda items, documents, recordings and motions. Billed as one records request. [Reference and playground for retrieve a meeting](https://data.heytownhall.com/docs/reference/meetings/get-v1-meetings-id) Path: `{id}` such as 123456. ## Agenda items ### `GET /v1/agenda-items` **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. [Reference and playground for list agenda items](https://data.heytownhall.com/docs/reference/meetings/get-v1-agenda-items) | Parameter | What it takes | | -------------- | ------------------------------------------------------------------------ | | `jurisdiction` | A jurisdiction id. | | `region` | A two-letter province or state code. | | `country` | CA or US. | | `topic` | A business topic id (GET /v1/topics lists the tags given). | | `from` | On or after this date (YYYY-MM-DD). | | `to` | On or before this date (YYYY-MM-DD). | | `since` | Records read at or after this instant: what is new since your last read. | | `meeting` | A meeting id. | Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)). | Field | Type | What it holds | | ----------------- | --------------- | ------------------------------------------------------------------- | | `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. | ## Meeting documents ### `GET /v1/meeting-documents` **List meeting documents.** Agenda packages, minutes and attachments a meeting lists, with their links. Billed as one records request a page. Filters: jurisdiction, region, country, kind, from, to, since, meeting. [Reference and playground for list meeting documents](https://data.heytownhall.com/docs/reference/meetings/get-v1-meeting-documents) | Parameter | What it takes | | -------------- | ------------------------------------------------------------------------ | | `jurisdiction` | A jurisdiction id. | | `region` | A two-letter province or state code. | | `country` | CA or US. | | `kind` | agenda_package, minutes, attachment, … | | `from` | On or after this date (YYYY-MM-DD). | | `to` | On or before this date (YYYY-MM-DD). | | `since` | Records read at or after this instant: what is new since your last read. | | `meeting` | A meeting id. | Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)). | Field | Type | What it holds | | ----------------- | -------------- | --------------------------------------------------------------- | | `id` | string | | | `meeting_id` | string | | | `jurisdiction_id` | string | | | `country` | string or null | | | `region` | string or null | | | `meeting_date` | string | YYYY-MM-DD. | | `item_position` | number or null | | | `kind` | string or null | | | `title` | string or null | | | `format` | string or null | | | `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. | ## Motions ### `GET /v1/motions` **List motions.** Motions as the minutes print them: mover, seconder, outcome and the count of votes, with each key decision's kind, topic and action. Billed as one records request a page. Filters: jurisdiction, region, country, kind, topic, from, to, since, meeting. [Reference and playground for list motions](https://data.heytownhall.com/docs/reference/decisions/get-v1-motions) | Parameter | What it takes | | -------------- | ------------------------------------------------------------------------ | | `jurisdiction` | A jurisdiction id. | | `region` | A two-letter province or state code. | | `country` | CA or US. | | `kind` | A key decision's kind, such as bylaw_reading or contract_award. | | `topic` | A business topic id (GET /v1/topics lists the tags given). | | `from` | On or after this date (YYYY-MM-DD). | | `to` | On or before this date (YYYY-MM-DD). | | `since` | Records read at or after this instant: what is new since your last read. | | `meeting` | A meeting id. | Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)). | Field | Type | What it holds | | ----------------- | --------------- | ------------------------------------------------------------------------ | | `id` | string | | | `meeting_id` | string | | | `jurisdiction_id` | string | | | `country` | string or null | | | `region` | string or null | | | `meeting_date` | string | YYYY-MM-DD. | | `position` | number | | | `item_position` | number or null | | | `number` | string or null | | | `text` | string | | | `mover` | string or null | | | `seconder` | string or null | | | `outcome` | string or null | carried, defeated, tabled, referred, withdrawn — as printed, normalised. | | `unanimous` | boolean or null | | | `votes_for` | number or null | | | `votes_against` | number or null | | | `kinds` | array of string | | | `topics` | array of string | | | `actions` | array of string | | | `business_topics` | array of string | | | `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. | ### `GET /v1/motions/{id}` **Retrieve a motion.** One motion with each member's recorded vote. Billed as one records request. [Reference and playground for retrieve a motion](https://data.heytownhall.com/docs/reference/decisions/get-v1-motions-id) Path: `{id}` such as 123456. ## Recorded votes ### `GET /v1/votes` **List recorded votes.** Each member's vote on a motion, as the minutes print it; never derived. A member away when the vote was taken is left out. Billed as one records request a page. Filters: jurisdiction, from, to, since, meeting, motion. [Reference and playground for list recorded votes](https://data.heytownhall.com/docs/reference/decisions/get-v1-votes) | Parameter | What it takes | | -------------- | ------------------------------------------------------------------------ | | `jurisdiction` | A jurisdiction id. | | `from` | On or after this date (YYYY-MM-DD). | | `to` | On or before this date (YYYY-MM-DD). | | `since` | Records read at or after this instant: what is new since your last read. | | `meeting` | A meeting id. | | `motion` | A motion id. | Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)). | Field | Type | What it holds | | ----------------- | -------------- | --------------------------------------------------------------- | | `id` | string | | | `motion_id` | string | | | `meeting_id` | string | | | `jurisdiction_id` | string | | | `meeting_date` | string | YYYY-MM-DD. | | `member_name` | string | | | `vote` | string | for, against, abstain, as the minutes print it. | | `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. | ## Attendance ### `GET /v1/attendance` **List attendance.** Who the minutes say was present or absent at a meeting. Billed as one records request a page. Filters: jurisdiction, from, to, since, meeting. [Reference and playground for list attendance](https://data.heytownhall.com/docs/reference/decisions/get-v1-attendance) | Parameter | What it takes | | -------------- | ------------------------------------------------------------------------ | | `jurisdiction` | A jurisdiction id. | | `from` | On or after this date (YYYY-MM-DD). | | `to` | On or before this date (YYYY-MM-DD). | | `since` | Records read at or after this instant: what is new since your last read. | | `meeting` | A meeting id. | Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)). | Field | Type | What it holds | | ----------------- | -------------- | --------------------------------------------------------------- | | `id` | string | | | `meeting_id` | string | | | `jurisdiction_id` | string | | | `meeting_date` | string | YYYY-MM-DD. | | `member_name` | string | | | `office` | string or null | | | `attendance` | string | | | `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. | ## Recordings ### `GET /v1/recordings` **List recordings.** Meeting videos and audio, and whether a transcript is held. Billed as one records request a page. Filters: jurisdiction, from, to, since, meeting. [Reference and playground for list recordings](https://data.heytownhall.com/docs/reference/meetings/get-v1-recordings) | Parameter | What it takes | | -------------- | ------------------------------------------------------------------------ | | `jurisdiction` | A jurisdiction id. | | `from` | On or after this date (YYYY-MM-DD). | | `to` | On or before this date (YYYY-MM-DD). | | `since` | Records read at or after this instant: what is new since your last read. | | `meeting` | A meeting id. | Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)). | Field | Type | What it holds | | ------------------ | -------------- | --------------------------------------------------------------- | | `id` | string | | | `jurisdiction_id` | string | | | `meeting_id` | string or null | | | `provider` | string or null | | | `title` | string or null | | | `published_at` | string or null | ISO 8601 instant, UTC. | | `duration_seconds` | number or null | | | `has_transcript` | boolean | | | `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. | ## Transcripts A transcript page is billed on the transcripts meter, not the records meter. See [Billing](https://data.heytownhall.com/docs/billing). ### `GET /v1/meetings/{id}/transcript` **A meeting's transcript.** The meeting's recordings' transcript lines in order, without speaker labels. Billed as one transcripts request a page. An empty page means no transcript is held yet, never that nothing was said. [Reference and playground for a meeting's transcript](https://data.heytownhall.com/docs/reference/meetings/get-v1-meetings-id-transcript) Path: `{id}` such as 123456. Pages with `limit` and `cursor` ([pagination](https://data.heytownhall.com/docs/pagination)). | Field | Type | What it holds | | -------------- | -------------- | --------------------------------------------------------------- | | `id` | string | | | `recording_id` | string | | | `start_ms` | number | | | `end_ms` | number or null | | | `text` | string | | | `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. |