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

# Get observations for a series

> Returns the latest values by default. Add `?as_of=DATE` for point-in-time queries —
the killer feature that returns what was known at any historical date.

**Plan restriction:** `?as_of=` requires Pro plan or higher. Free plan returns latest data only.
Free users attempting `?as_of=` receive a 403 with upgrade instructions.




## OpenAPI

````yaml /openapi/v1.yaml get /v1/series/{id}/observations
openapi: 3.1.0
info:
  title: Vintl API
  version: 1.0.0
  description: >
    Point-in-time macro-economic and treasury data API.


    The killer feature: `?as_of=DATE` returns what economic data was known at
    any historical date.

    Requires Pro plan or higher — free plan returns latest data only.
  contact:
    name: Vintl Support
    url: https://vintl.io
  license:
    name: Proprietary
servers:
  - url: https://api.vintl.io
    description: Production
  - url: http://localhost:8080
    description: Local development
security:
  - ApiKeyAuth: []
tags:
  - name: Health
    description: Liveness and readiness probes
  - name: Auth
    description: API key validation and plan info
  - name: Treasury
    description: U.S. Treasury yield curve data (1990-present, never revised)
  - name: Macro
    description: Economic indicators with point-in-time vintage tracking
  - name: Series
    description: Series discovery and metadata
  - name: Insider
    description: SEC Form 4 insider trading data with cluster detection
paths:
  /v1/series/{id}/observations:
    get:
      tags:
        - Macro
      summary: Get observations for a series
      description: >
        Returns the latest values by default. Add `?as_of=DATE` for
        point-in-time queries —

        the killer feature that returns what was known at any historical date.


        **Plan restriction:** `?as_of=` requires Pro plan or higher. Free plan
        returns latest data only.

        Free users attempting `?as_of=` receive a 403 with upgrade instructions.
      parameters:
        - name: id
          in: path
          required: true
          schema:
            type: string
          example: GDPC1
        - name: as_of
          in: query
          schema:
            type: string
            format: date
          description: >
            **Point-in-time query.** Returns observations as they were known on
            this date.

            Example: `?as_of=2023-10-26` returns GDP at the advance estimate
            value ($22,491.567B),

            not today's revised value ($22,840.989B). Requires Pro plan or
            higher.
          example: '2023-10-26'
        - $ref: '#/components/parameters/from'
        - $ref: '#/components/parameters/to'
        - $ref: '#/components/parameters/limit'
        - $ref: '#/components/parameters/cursor'
      responses:
        '200':
          description: >
            Observations. When `as_of` is provided, includes `series` metadata
            and `as_of` field.
          content:
            application/json:
              schema:
                type: object
                properties:
                  object:
                    type: string
                    example: observation_series
                  request_id:
                    type: string
                  status:
                    type: string
                  as_of:
                    type: string
                    format: date
                    description: Present only when ?as_of= was used
                  series:
                    type: object
                    description: Present only when ?as_of= was used
                    properties:
                      id:
                        type: string
                      title:
                        type: string
                      frequency:
                        type: string
                  results:
                    type: array
                    items:
                      $ref: '#/components/schemas/Observation'
                  results_count:
                    type: integer
                  has_more:
                    type: boolean
                  next_cursor:
                    type: string
        '400':
          description: Invalid date format or date range
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/PlanUpgradeRequired'
        '429':
          $ref: '#/components/responses/RateLimited'
components:
  parameters:
    from:
      name: from
      in: query
      schema:
        type: string
        format: date
      description: Start date (YYYY-MM-DD)
    to:
      name: to
      in: query
      schema:
        type: string
        format: date
      description: End date (YYYY-MM-DD)
    limit:
      name: limit
      in: query
      schema:
        type: integer
        minimum: 1
        maximum: 1000
        default: 100
    cursor:
      name: cursor
      in: query
      schema:
        type: string
      description: Opaque pagination cursor from previous response
  schemas:
    Observation:
      type: object
      properties:
        date:
          type: string
          format: date-time
          example: '2023-07-01T00:00:00Z'
        value:
          type: string
          description: Decimal value as string (never float)
          example: '22491.567'
        as_of_date:
          type: string
          format: date-time
          description: The vintage date — when this value was published
          example: '2023-10-26T00:00:00Z'
        series_id:
          type: string
          example: GDPC1
        unit:
          type: string
          example: lin
        frequency:
          type: string
          example: Q
        source:
          type: string
          example: FRED
    Problem:
      type: object
      description: RFC 9457 Problem Details (Content-Type application/problem+json)
      properties:
        type:
          type: string
          format: uri
          example: https://macrodata.dev/errors/not-found
        title:
          type: string
          example: Not Found
        status:
          type: integer
          example: 404
        detail:
          type: string
          example: series 'INVALID' not found
        instance:
          type: string
          example: /v1/series/INVALID
        request_id:
          type: string
          example: req_19d40c11691b60ece4cc73351271260
        field:
          type: string
          description: Which field caused the error (on validation errors)
  responses:
    Unauthorized:
      description: Missing or invalid API key
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://macrodata.dev/errors/unauthorized
            title: Unauthorized
            status: 401
            detail: API key is required. Set the X-API-Key header.
            instance: /v1/ping
    PlanUpgradeRequired:
      description: Feature requires a higher plan
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
          example:
            type: https://macrodata.dev/errors/plan-upgrade-required
            title: Plan Upgrade Required
            status: 403
            detail: >-
              Point-in-time queries (?as_of) requires a Pro plan or higher.
              Upgrade at app.vintl.io/billing
    RateLimited:
      description: Rate limit exceeded
      headers:
        Retry-After:
          schema:
            type: integer
          description: Seconds until rate limit resets
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/Problem'
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-Key
      description: API key prefixed with `mda_live_sk_`

````