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

# Population change feed

> <Note>Change feed access not included in basic plans. Contact GemRate for more information.</Note> A feed of cards whose population has changed, ordered oldest-change first. Poll it to keep a local copy of population data in sync without re-fetching every card: read this feed, then re-fetch the returned ids from [`GET /v1/cards/{gemrate_id}/population`](/api-reference/cards/get-population-for-a-card).
## Cursoring
The feed is keyset-paginated by an opaque `cursor`. A typical loop:
1. First call: pass `since` (an ISO date) for an initial backfill. With
   neither `since` nor `cursor`, the feed defaults to today (UTC) — you
   get only the current day's changes, not a full-history scan.
2. Read every page until `has_more` is `false`, passing the returned
   `next_cursor` back as `cursor` each time.
3. Store the final `next_cursor`. Next time you poll, start from it —
   you'll only see ids that changed since.

Every response echoes `since`, the inclusive lower-bound date it covers (today, in UTC, when you passed neither `since` nor `cursor`), so a naive poll can see the baseline it defaulted to.
When you're caught up, the call returns an empty `gemrate_ids` with the same position echoed back in `next_cursor`, so you can keep polling with the same token. `cursor` takes precedence over `since` if both are sent.




## OpenAPI

````yaml /openapi.yaml get /v1/cards/population/changes
openapi: 3.0.3
info:
  title: GemRate API
  version: '1.0'
  description: >
    The GemRate API gives you programmatic access to graded trading-card data:
    look up a specific cert, get population reports and their history, look up
    and search for cards, and download bulk catalogs.

    ## Quickstart

    1. **Get an API key.** Contact the GemRate team to request one. 2. **Send it
    on every request** in the `x-api-key` header. 3. **Make a call:**

    ```bash curl https://api.gemrate.com/v1/certs/psa/47178561 \
      -H "x-api-key: YOUR_API_KEY"
    ```

    ```json {
      "data": {
        "description": "1986 Fleer Michael Jordan 57",
        "universal_gemrate_id": "25b4432f12a5d6ec29a6f00490200416d5dfa242",
        "gemrate_id": "25b4432f12a5d6ec29a6f00490200416d5dfa242",
        "is_universal_match": true,
        "gemrate_url": "https://gemrate.com/card/25b4432f12a5d6ec29a6f00490200416d5dfa242",
        "grader": "psa",
        "grader_data": {
          "cert": "47178561",
          "grade": "psa_5",
          "grade_label": "5",
          "set_url": "https://www.psacard.com/pop/basketball-cards/1986/fleer/36766",
          "population_context": {
            "grade_population": 2080,
            "population_higher": 22520,
            "total_population": 30810,
            "gem_total": 340,
            "gem_rate": 0.011
          },
          "spec_id": "299576"
        }
      },
      "meta": { "request_id": "req_abc123" }
    } ```

    Shared identity fields sit at the top level; everything specific to the
    grading company (grade, links, and grader-specific extras) is nested under
    `grader_data`.

    A cert is a specific graded copy of a card; the `gemrate_id` in the response
    points to that card, which you can then explore via the `/v1/cards`
    endpoints.

    ## Base URL

    All routes live under the `/v1` version prefix:

    ``` https://api.gemrate.com/v1 ```

    All endpoints are served over HTTPS. Reads are `GET` requests. The contract
    evolves additive-only within `v1`; a genuinely incompatible change would
    ship as a parallel `/v2`.

    ## Authentication

    Pass your key in the `x-api-key` header on every request:

    ``` x-api-key: YOUR_API_KEY ```

    - Missing or invalid key → `401`. - Valid key without access to a resource →
    `403`.

    ## Response shape

    Every successful response is an object with two top-level keys:

    - `data` — the result (an object, or an array for list endpoints). - `meta`
    — metadata, always including a `request_id` you can quote in
      support requests.

    ```json { "data": { }, "meta": { "request_id": "req_abc123" } } ```

    ## Lean payloads and sub-resources

    Cert and spec lookups return a lean default payload (identity only). Heavier
    data lives on dedicated sub-resource endpoints — population and images each
    have their own URL:

    ```bash curl "https://api.gemrate.com/v1/certs/psa/47178561/population" \
      -H "x-api-key: YOUR_API_KEY"
    ```

    ## Errors

    Errors return a non-2xx status and a body with a stable, machine-readable
    `code` you can branch on (the `message` is for humans and may change):

    ```json {
      "error": {
        "code": "cert_not_found",
        "message": "No PSA cert found for cert 12345678.",
        "details": { "grader": "psa", "cert": "12345678" }
      },
      "meta": { "request_id": "req_abc123" }
    } ```

    | Status | When | |--------|------| | `200` | Success (including an empty
    list — `data: []`). | | `202` | Accepted, but still processing — retry
    shortly. | | `400` | Your request was malformed or invalid. | | `401` |
    Missing or invalid API key. | | `403` | Your key isn't allowed to access
    this resource. | | `404` | The specific item you asked for doesn't exist in
    our data. | | `429` | You've hit the rate limit — slow down. | | `500` |
    Something went wrong on our end. |

    ## Conventions

    - JSON field and query-parameter names use `snake_case`. - Dates are
    `YYYY-MM-DD`; timestamps are ISO-8601 UTC. - Booleans in the query string
    are the strings `true` / `false`.
servers:
  - url: https://api.gemrate.com
    description: Production
security:
  - ApiKeyAuth: []
tags:
  - name: Cards
    description: >-
      The card itself (one gemrate_id) — its population, history, search, and
      the population change feed.
  - name: Certs
    description: A specific graded copy of a card, identified by grader and cert number.
  - name: Specs
    description: A grading company's catalog entry for a card; resolves to the card.
  - name: Catalogs
    description: Bulk CSV downloads of graded-card data.
  - name: Grades
    description: The grade map — each grade's per-grader label keys and display names.
paths:
  /v1/cards/population/changes:
    get:
      tags:
        - Cards
      summary: Population change feed
      description: >
        <Note>Change feed access not included in basic plans. Contact GemRate
        for more information.</Note> A feed of cards whose population has
        changed, ordered oldest-change first. Poll it to keep a local copy of
        population data in sync without re-fetching every card: read this feed,
        then re-fetch the returned ids from [`GET
        /v1/cards/{gemrate_id}/population`](/api-reference/cards/get-population-for-a-card).

        ## Cursoring

        The feed is keyset-paginated by an opaque `cursor`. A typical loop:

        1. First call: pass `since` (an ISO date) for an initial backfill. With
           neither `since` nor `cursor`, the feed defaults to today (UTC) — you
           get only the current day's changes, not a full-history scan.
        2. Read every page until `has_more` is `false`, passing the returned
           `next_cursor` back as `cursor` each time.
        3. Store the final `next_cursor`. Next time you poll, start from it —
           you'll only see ids that changed since.

        Every response echoes `since`, the inclusive lower-bound date it covers
        (today, in UTC, when you passed neither `since` nor `cursor`), so a
        naive poll can see the baseline it defaulted to.

        When you're caught up, the call returns an empty `gemrate_ids` with the
        same position echoed back in `next_cursor`, so you can keep polling with
        the same token. `cursor` takes precedence over `since` if both are sent.
      operationId: getChanges
      parameters:
        - name: since
          in: query
          required: false
          description: >
            ISO date (`YYYY-MM-DD`), inclusive — return cards changed on or
            after this day. Interpreted in UTC; must be on or before today (UTC)
            and within the last 30 days. Ignored when `cursor` is also sent.
          schema:
            type: string
            format: date
            example: '2026-06-01'
        - name: cursor
          in: query
          required: false
          description: >
            Opaque pagination token from a prior response's `next_cursor`. Wins
            over `since`. Omit both to default to today (UTC).
          schema:
            type: string
        - name: limit
          in: query
          required: false
          description: Page size, 1–10000.
          schema:
            type: integer
            minimum: 1
            maximum: 10000
            default: 1000
      responses:
        '200':
          description: A page of changed card ids.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/ChangeFeed'
                  meta:
                    $ref: '#/components/schemas/Meta'
              example:
                data:
                  gemrate_ids:
                    - 25b4432f12a5d6ec29a6f00490200416d5dfa242
                    - 3a1f9c0b7e2d4856af13c6900128b4e7d9c0a1f2
                  count: 2
                  since: '2026-06-01'
                  has_more: true
                  next_cursor: >-
                    MjAyNi0wNi0wMXwzYTFmOWMwYjdlMmQ0ODU2YWYxM2M2OTAwMTI4YjRlN2Q5YzBhMWYy
                meta:
                  request_id: req_abc123
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/ServerError'
components:
  schemas:
    ChangeFeed:
      type: object
      description: One page of the population change feed.
      properties:
        gemrate_ids:
          type: array
          description: >-
            Card ids whose population changed, oldest change first. Empty when
            caught up.
          items:
            type: string
        count:
          type: integer
          description: Number of ids in this page (`gemrate_ids.length`).
        since:
          type: string
          format: date
          description: >
            Inclusive lower-bound date (`YYYY-MM-DD`) this response covers — the
            requested `since`, the resumed cursor's date, or today (UTC) when
            the caller passed neither. Lets a naive poll see the baseline it
            defaulted to.
          example: '2026-06-01'
        has_more:
          type: boolean
          description: >-
            Whether more changes are waiting — keep paging with `next_cursor`
            while true.
        next_cursor:
          type: string
          description: >
            Opaque token marking the end of this page. Pass it back as `cursor`
            to get the next page or to resume polling later. On an empty page it
            echoes the current position so you can keep polling with the same
            token.
      required:
        - gemrate_ids
        - count
        - since
        - has_more
        - next_cursor
    Meta:
      type: object
      description: Metadata attached to every response.
      properties:
        request_id:
          type: string
          description: A unique ID for this request; quote it in support requests.
          example: req_abc123
      required:
        - request_id
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              $ref: '#/components/schemas/ErrorCode'
            message:
              type: string
              description: A human-readable description. May change; don't parse it.
            details:
              type: object
              description: Optional structured context about the error.
              additionalProperties: true
          required:
            - code
            - message
        meta:
          $ref: '#/components/schemas/Meta'
      required:
        - error
    ErrorCode:
      type: string
      description: >-
        A stable, machine-readable error code. Branch on this. Tolerate new
        values.
      enum:
        - invalid_grader
        - invalid_cert
        - invalid_parameter
        - invalid_date_range
        - cert_not_found
        - card_not_found
        - spec_not_found
        - unauthorized
        - forbidden
        - rate_limited
        - processing
        - internal_error
  responses:
    BadRequest:
      description: Your request was malformed or invalid.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: invalid_grader
              message: Unknown grader 'foo'.
            meta:
              request_id: req_abc123
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: unauthorized
              message: Missing or invalid API key.
            meta:
              request_id: req_abc123
    Forbidden:
      description: Your key isn't allowed to access this resource.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: forbidden
              message: Your key does not have access to this resource.
            meta:
              request_id: req_abc123
    RateLimited:
      description: You've hit the rate limit — slow down.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: rate_limited
              message: Too many requests.
            meta:
              request_id: req_abc123
    ServerError:
      description: Something went wrong on our end.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            error:
              code: internal_error
              message: Something went wrong.
            meta:
              request_id: req_abc123
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````