---
title: "List upcoming agenda hits"
method: GET
path: "/api/v1/public/upcoming-agenda-hits"
tags: ["Agenda hits"]
---

# List upcoming agenda hits

`GET /api/v1/public/upcoming-agenda-hits`

## Request

- Base URL: `https://aicdapi.com`
- URL: `https://aicdapi.com/api/v1/public/upcoming-agenda-hits`
- Auth: none required

Returns upcoming hits for one topic in meeting-time order. Send `topicSlug`
or its legacy alias `topic`: the request must carry one of them, and `topicSlug` wins
when both are present. A missing or uncovered topic is a 400, so the example request
below sends a topic.

Cursor pagination is the default. The legacy `page` parameter remains
available through page 100. Do not send `cursor` and `page` together.
Cursor responses contain `hits` and `nextCursor`, plus `totalCount` when
`count=true`. Legacy page responses retain `hits`, `totalCount`, `page`,
and `pageSize`. Every successful response includes `meta.pagination`.

Each hit carries `matchId`: that is the id `GET /api/v1/public/agenda-hits/{matchId}`
takes, and the recent-hits list does not return ids. An empty `hits` array is a
normal answer — no upcoming classified hit for that topic in the public coverage
set right now — and a backend failure returns the same empty page with HTTP 200.
Neither is proof that no body meets.

## Query parameters

- `topicSlug` string
- `topic` string
- `cursor` string
- `page` integer
- `count` true

## Response `200`

Upcoming agenda hits.

- UpcomingAgendaHitsEnvelope
  - `data` union, required: One page of upcoming hits. A cursor request returns `hits` and `nextCursor`, plus `totalCount` when `count=true`; a legacy `page` request returns `hits`, `totalCount`, `page`, and `pageSize`.
    - object: A cursor page. `data.nextCursor`, and `data.totalCount` when `count=true`.
      - `hits` UpcomingAgendaHit[], required: Upcoming classified hits for the requested topic in meeting-time order. An empty array means no upcoming classified hit for that topic right now; a backend failure returns the same empty page, so it is not proof that a body has no meetings.
        - `matchId` string, uuid, required: Id for `GET /api/v1/public/agenda-hits/{matchId}`.
        - `jurisdictionSlug` string, required
        - `jurisdictionName` string, required
        - `bodyName` string, required
        - `topicSlug` string, required
        - `meetingAt` string, date-time, required
        - `meetingTimePrecision` 'date' | 'time' | 'unknown' | 'null', nullable: Optional precision. date has no supplied clock; time is a verified source clock; unknown is unverified. Absent or null preserves pre-contract legacy precision and does not certify a clock.
        - `title` string, required
        - `summary` string, required
        - `businessImpact` string, required
        - `evidenceQuote` string, required
        - `sourceUrl` string, uri, required
        - `confidence` integer, required
        - `affectedLocation` AffectedLocationValue, required
          - `status` 'stated' | 'not_stated', required
          - `locations` AffectedLocation[], required
            - `kind` 'exact_address' | 'parcel_or_case' | 'zip_code' | 'council_district' | 'corridor' | 'named_development' | 'neighborhood' | 'citywide', required
            - `sourceText` string, required
        - `proceduralContext` AgendaProceduralContext, required
          - `proceduralStage` 'proposed' | 'scheduled' | 'recommended' | 'continued' | 'approved' | 'denied' | 'adopted' | 'unknown', required
          - `actingBodyRole` 'recommending' | 'final_decision_maker' | 'unknown', required
          - `nextBodyName` string, nullable, required
          - `nextMeetingDate` string, date, nullable, required
          - `actionKind` 'public_comment' | 'registration' | 'meeting' | 'staff_contact' | 'unknown', required
          - `actionUrl` string, uri, nullable, required
      - `nextCursor` string, nullable, required: Cursor responses only. Null when the last page was returned.
      - `totalCount` integer: Legacy `page` responses, and cursor responses that ask for `count=true`.
      - `page` integer: Legacy `page` responses only.
      - `pageSize` 10: Legacy `page` responses only.
    - object: A legacy `page` response. `data.page`, `data.pageSize`, and `data.totalCount`.
      - `hits` UpcomingAgendaHit[], required: Upcoming classified hits for the requested topic in meeting-time order. An empty array means no upcoming classified hit for that topic right now; a backend failure returns the same empty page, so it is not proof that a body has no meetings.
        - `matchId` string, uuid, required: Id for `GET /api/v1/public/agenda-hits/{matchId}`.
        - `jurisdictionSlug` string, required
        - `jurisdictionName` string, required
        - `bodyName` string, required
        - `topicSlug` string, required
        - `meetingAt` string, date-time, required
        - `meetingTimePrecision` 'date' | 'time' | 'unknown' | 'null', nullable: Optional precision. date has no supplied clock; time is a verified source clock; unknown is unverified. Absent or null preserves pre-contract legacy precision and does not certify a clock.
        - `title` string, required
        - `summary` string, required
        - `businessImpact` string, required
        - `evidenceQuote` string, required
        - `sourceUrl` string, uri, required
        - `confidence` integer, required
        - `affectedLocation` AffectedLocationValue, required
          - `status` 'stated' | 'not_stated', required
          - `locations` AffectedLocation[], required
            - `kind` 'exact_address' | 'parcel_or_case' | 'zip_code' | 'council_district' | 'corridor' | 'named_development' | 'neighborhood' | 'citywide', required
            - `sourceText` string, required
        - `proceduralContext` AgendaProceduralContext, required
          - `proceduralStage` 'proposed' | 'scheduled' | 'recommended' | 'continued' | 'approved' | 'denied' | 'adopted' | 'unknown', required
          - `actingBodyRole` 'recommending' | 'final_decision_maker' | 'unknown', required
          - `nextBodyName` string, nullable, required
          - `nextMeetingDate` string, date, nullable, required
          - `actionKind` 'public_comment' | 'registration' | 'meeting' | 'staff_contact' | 'unknown', required
          - `actionUrl` string, uri, nullable, required
      - `nextCursor` string, nullable: Cursor responses only. Null when the last page was returned.
      - `totalCount` integer, required: Legacy `page` responses, and cursor responses that ask for `count=true`.
      - `page` integer, required: Legacy `page` responses only.
      - `pageSize` 10, required: Legacy `page` responses only.
  - `meta` object, required
    - `pagination` PaginationMeta, required
      - `limit` 10, required
      - `returned` integer, required
      - `nextCursor` string, nullable, required: Opaque cursor for the next page, or null when traversal is complete.

## Other responses

- `400`: A path or query parameter is invalid or unsupported.
- `429`: More than 120 requests were made by this client IP in 60 seconds.
- `500`: The request could not be completed because of an internal error.

---

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