---
title: "Poll one subscription's change feed"
method: GET
path: "/api/v1/data/subscriptions/{subscriptionId}/changes"
tags: ["Customer civic data"]
---

# Poll one subscription's change feed

`GET /api/v1/data/subscriptions/{subscriptionId}/changes`

## Request

- Base URL: `https://aicdapi.com`
- URL: `https://aicdapi.com/api/v1/data/subscriptions/{subscriptionId}/changes`
- Auth: HTTP bearer

Limited, machine-only release. Returns the next ordered page of the durable civic change feed for one live feed. The resource filter is fixed by the subscription and cannot be overridden on the request: only `cursor` and `limit` are accepted. Without a cursor, polling starts at the start cursor captured when the feed was created; from then on the caller sends the cursor it stored after committing the previous page, exactly as on `GET /api/v1/data/changes`. The cursor stays an opaque position, not an authorization: it is bound to the subscription's resource filter, and it is derived from the account's feed position rather than from the key secret, so a new feed registered by a replacement key can resume from a retained position of the old feed while that position is still replayable. The stored start position carries no exemption from the same retention window. The server never advances the cursor and keeps no acknowledgement: a client advances only after its own work commits. The request is served only while the feed's owner, the presented key, and the account's paid eligibility are all current and the feed is unrevoked; otherwise the poll is refused before any read. Replay is retained for 30 days and an older cursor is refused rather than silently skipped.

## Path parameters

- `subscriptionId` string, uuid, required

## Query parameters

- `cursor` string
- `limit` integer

## Response `200`

Ordered change page for the feed's pinned resource filter. The envelope and cursor format are the durable change feed's.

- FeedSubscriptionChangesEnvelope
  - `data` object, required
    - `items` CivicChangeItem[], required: The ordered change page, each item carrying its own cursor. Item keys and nullability are the durable change feed's.
      - union
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'jurisdictions', required
          - `operation` 'upsert', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` CivicDataJurisdictions, required
            - `id` string, uuid, required
            - `slug` string, required
            - `name` string, required
            - `type` 'city' | 'town' | 'village' | 'county' | 'special_district', required
            - `state` string, required
            - `countyName` string, nullable, required
            - `nctcogMember` boolean, required
            - `population` integer, nullable, required
            - `timezone` string, required
            - `websiteUrl` string, nullable, required
            - `createdAt` string, date-time, required
            - `updatedAt` string, date-time, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'jurisdictions', required
          - `operation` 'remove', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` unknown, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'public_bodies', required
          - `operation` 'upsert', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` CivicDataPublicBodies, required
            - `id` string, uuid, required
            - `jurisdictionId` string, uuid, required
            - `slug` string, required
            - `name` string, required
            - `bodyType` 'city_council' | 'commissioners_court' | 'planning_zoning' | 'board_adjustment' | 'economic_development' | 'parks' | 'other', required
            - `active` boolean, required
            - `createdAt` string, date-time, required
            - `updatedAt` string, date-time, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'public_bodies', required
          - `operation` 'remove', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` unknown, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'source_endpoints', required
          - `operation` 'upsert', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` CivicDataSourceEndpoints, required
            - `id` string, uuid, required
            - `publicBodyId` string, uuid, required
            - `sourceSystem` 'legistar' | 'civicplus_agenda_center' | 'civicweb' | 'civicclerk' | 'granicus' | 'municode' | 'onbase_agenda_online' | 'pdf_directory' | 'arcgis_feature_service' | 'docspublished' | 'novusagenda' | 'agendaquick', required
            - `recordKind` 'agenda' | 'record_stream', required
            - `officialSourceUrl` string, required
            - `pollIntervalMinutes` integer, required
            - `lastSuccessAt` string, date-time, nullable, required
            - `lastErrorAt` string, date-time, nullable, required
            - `errorCategory` 'timeout' | 'dns' | 'authorization' | 'not_found' | 'size_limit' | 'invalid_document' | 'upstream_failure', nullable, required
            - `active` boolean, required
            - `createdAt` string, date-time, required
            - `updatedAt` string, date-time, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'source_endpoints', required
          - `operation` 'remove', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` unknown, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'topics', required
          - `operation` 'upsert', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` CivicDataTopics, required
            - `id` string, uuid, required
            - `slug` string, required
            - `name` string, required
            - `publicLabel` string, required
            - `description` string, required
            - `keywords` string[], required
            - `negativeKeywords` string[], required
            - `selectable` true, required
            - `classificationActive` boolean, required
            - `taxonomyManaged` boolean, required
            - `createdAt` string, date-time, required
            - `updatedAt` string, date-time, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'topics', required
          - `operation` 'remove', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` unknown, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'meetings', required
          - `operation` 'upsert', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` CivicDataMeetings, required
            - `id` string, uuid, required
            - `sourceEndpointId` string, uuid, required
            - `publicBodyId` string, uuid, required
            - `externalId` string, required
            - `title` 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.
            - `status` 'scheduled' | 'cancelled' | 'completed' | 'unknown', required
            - `agendaUrl` string, nullable, required
            - `packetUrl` string, nullable, required
            - `minutesUrl` string, nullable, required
            - `videoUrl` string, nullable, required
            - `sourceDocuments` object[], required
              - …
            - `sourceHash` string, required
            - `createdAt` string, date-time, required
            - `updatedAt` string, date-time, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'meetings', required
          - `operation` 'remove', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` unknown, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'documents', required
          - `operation` 'upsert', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` CivicDataDocuments, required
            - `id` string, uuid, required
            - `meetingId` string, uuid, nullable, required
            - `sourceEndpointId` string, uuid, required
            - `documentType` 'agenda' | 'packet' | 'minutes' | 'staff_report' | 'attachment' | 'html', required
            - `sourceUrl` string, required
            - `contentType` string, nullable, required
            - `sha256` string, required
            - `fetchedAt` string, date-time, required
            - `createdAt` string, date-time, required
            - `extraction` object, required
              - …
            - `archive` object, required
              - …
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'documents', required
          - `operation` 'remove', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` unknown, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'agenda_items', required
          - `operation` 'upsert', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` CivicDataAgendaItems, required
            - `id` string, uuid, required
            - `meetingId` string, uuid, required
            - `documentId` string, uuid, nullable, required
            - `externalId` string, nullable, required
            - `itemNumber` string, nullable, required
            - `title` string, required
            - `rawText` string, required
            - `normalizedText` string, required
            - `actionType` string, required
            - `pageNumber` integer, nullable, required
            - `sourceUrl` string, nullable, required
            - `sourceHash` string, required
            - `classification` object, required
              - …
            - `createdAt` string, date-time, required
            - `updatedAt` string, date-time, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'agenda_items', required
          - `operation` 'remove', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` unknown, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'topic_matches', required
          - `operation` 'upsert', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` CivicDataTopicMatches, required
            - `id` string, uuid, required
            - `agendaItemId` string, uuid, required
            - `topicId` string, uuid, required
            - `matchMethod` 'keyword' | 'llm' | 'manual', required
            - `confidence` integer, required
            - `headline` string, nullable, required
            - `summary` string, required
            - `businessImpact` string, required
            - `evidenceQuote` string, required
            - `affectedLocation` object, required
            - `proceduralStage` 'proposed' | 'scheduled' | 'recommended' | 'continued' | 'approved' | 'denied' | 'adopted' | 'unknown', required
            - `actingBodyRole` 'recommending' | 'final_decision_maker' | 'unknown', required
            - `nextBodyName` string, nullable, required
            - `nextMeetingDate` string, nullable, required
            - `actionKind` 'public_comment' | 'registration' | 'meeting' | 'staff_contact' | 'unknown', required
            - `actionUrl` string, nullable, required
            - `model` string, nullable, required
            - `classifiedAt` string, date-time, required
            - `createdAt` string, date-time, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'topic_matches', required
          - `operation` 'remove', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` unknown, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'classification_evidence', required
          - `operation` 'upsert', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` CivicDataClassificationEvidence, required
            - `id` string, uuid, required
            - `agendaItemId` string, uuid, nullable, required
            - `topicId` string, uuid, nullable, required
            - `decision` 'keyword_no_candidate' | 'llm_no_match' | 'llm_match' | 'error', required
            - `candidateTopicSlugs` string[], required
            - `provider` string, nullable, required
            - `model` string, nullable, required
            - `confidence` integer, nullable, required
            - `headline` string, nullable, required
            - `summary` string, nullable, required
            - `businessImpact` string, nullable, required
            - `evidenceQuote` string, nullable, required
            - `affectedLocation` object, required
            - `proceduralStage` string, nullable, required
            - `actingBodyRole` string, nullable, required
            - `nextBodyName` string, nullable, required
            - `nextMeetingDate` string, nullable, required
            - `actionKind` string, nullable, required
            - `actionUrl` string, nullable, required
            - `errorCategory` 'classification_failed', nullable, required
            - `classifiedAt` string, date-time, required
            - `createdAt` string, date-time, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'classification_evidence', required
          - `operation` 'remove', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` unknown, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'civic_events', required
          - `operation` 'upsert', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` CivicDataCivicEvents, required
            - `id` string, uuid, required
            - `jurisdictionId` string, uuid, required
            - `publicBodyId` string, uuid, nullable, required
            - `sourceEndpointId` string, uuid, required
            - `recordType` 'building_permit' | 'agenda_item_match', required
            - `category` 'residential' | 'commercial' | 'infrastructure' | 'government' | 'utilities' | 'education' | 'public_safety' | 'economic_development', required
            - `title` string, required
            - `summary` string, nullable, required
            - `evidenceQuote` string, nullable, required
            - `evidence` object, required
            - `sourceUrl` string, required
            - `occurredAt` string, date-time, nullable, required
            - `detectedAt` string, date-time, required
            - `externalRef` string, required
            - `dedupeHash` string, required
            - `address` string, nullable, required
            - `latitude` number, nullable, required
            - `longitude` number, nullable, required
            - `parcelId` string, nullable, required
            - `impactLevel` string, nullable, required
            - `impact` object, nullable, required
            - `payload` object, required
            - `createdAt` string, date-time, required
            - `updatedAt` string, date-time, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'civic_events', required
          - `operation` 'remove', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` unknown, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'aliases', required
          - `operation` 'upsert', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` CivicDataAliases, required
            - `id` string, uuid, required
            - `namespace` string, required
            - `resource` 'jurisdictions' | 'public_bodies' | 'source_endpoints' | 'topics' | 'meetings' | 'documents' | 'agenda_items' | 'topic_matches' | 'classification_evidence' | 'civic_events', required
            - `legacyId` string, required
            - `upstreamId` string, uuid, required
            - `createdAt` string, date-time, required
            - `updatedAt` string, date-time, required
        - object
          - `cursor` string, required: Opaque continuation token. Store and replay without modification.
          - `resource` 'aliases', required
          - `operation` 'remove', required
          - `recordId` string, uuid, required
          - `version` string, required: Monotonic decimal bigint. Compare as an integer, never as floating point.
          - `changedAt` string, date-time, required: UTC timestamp ending in Z.
          - `data` unknown, required
  - `meta` object, required
    - `nextCursor` string, required: Opaque continuation token. Persist it even when no items come back.
    - `hasMore` boolean, required: True when another page is available now.
    - `replayExpiresAt` string, date-time, required: When this position stops being replayable. After it, the cursor is refused with 410.

## Other responses

- `400`: An unknown or repeated query key, a limit that is not a positive integer, or a cursor that cannot be decoded or was minted for a different resource filter.
- `401`: The API key is missing, malformed, unknown, revoked, expired, or belongs to a customer that is not active.
- `403`: The key lacks the required grant, the account has no billing channel while billing enforcement is on, is not paid through, or is not on a current Pro or Ultra paid tier.
- `404`: The feed is unknown, belongs to another account or another key, is not a UUID at all, or has been revoked. A revoked feed is not distinguishable from a missing one.
- `410`: The supplied position is older than the retained replay floor, and this feed's stored start cursor may have aged out as well. Retrying that position cannot make progress, and omitting the cursor must not be used to skip unread changes. Reconcile from a fresh export snapshot (`POST /api/v1/data/snapshots`, which needs `civic:export`) and continue this feed by sending that snapshot's `boundaryCursor` as `cursor`: a boundary cursor carries no resource binding, so the feed's pinned filter accepts it, and it closes the gap between the frozen export and later commits. New registration is required after key rotation, but not for cursor expiry alone.
- `413`: The serialized response exceeds the response size allowance on your account.
- `429`: Either a per-account allowance was exhausted or the account-wide abuse ceiling was reached. The abuse ceiling is account-wide, is not charged against the paid quota, and is charged after the identity lookup and before a revoked, expired, unpaid, or scope-denied rejection is decided.
- `500`: Unexpected failure. No private database detail is returned.
- `503`: Authentication, limit store, or feed state is unavailable.
- `504`: The read deadline for this operation elapsed.

---

[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)