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

# Get vault history by slug

> Returns USD TVL and outstanding share supply summed across every currently linked deployment of an enabled logical vault, including hidden vaults. Uses UTC-aligned snapshots and timestamp pagination. A deployment contributes zero before its indexed creation time; after creation, missing snapshots or USD prices produce null TVL, never a partial sum. Does not carry values forward. Missing supply or a missing snapshot after deployment creation produces null total_supply, independent of USD price availability. APY and unit_price come from the Admin-selected primary deployment at the same timestamp, identified by meta.resolved_vault_id. Missing primary snapshots yield null primary metrics; APY respects Admin visibility. TVL is USD-only because deployment numeraires may differ; native TVL remains available on the primary/per-deployment endpoints. This is a sum of deployment TVLs, not the legacy asset-position valuation. Unknown or disabled slugs return 404; incomplete deployment metadata returns 503.

Returns historical metrics for the logical vault identified by its slug:

| Field | Scope |
| - | - |
| `tvl.usd` | Sum across all currently linked deployments |
| `apy_7d`, `apy_30d`, `apy_90d` | Admin-selected primary deployment; respects APY visibility |
| `unit_price` | Primary deployment, in its numeraire-token units per share |
| `total_supply` | Sum of outstanding shares across all currently linked deployments |

`meta.resolved_vault_id` identifies the primary supplying the deployment-local
metrics. Rates and share prices are not summed or averaged.
The `/primary/timeseries` endpoint still returns only primary-deployment data,
including `tvl.native`. The logical-vault endpoint exposes USD TVL only because
linked deployments can use different numeraires.

Snapshots are aligned by timestamp, with the same date range, granularity,
ordering, and cursor parameters as deployment history. A missing primary
snapshot makes its APY and price null at that timestamp; another
deployment's metrics are never substituted. A missing USD price does not hide
otherwise available supply or primary metrics.

Before a deployment's indexed creation time, it contributes zero to TVL. After
creation, a missing snapshot or USD price makes the aggregate `tvl.usd` null;
clients should render a gap rather than zero or a partial sum. Supply follows
the same inception and snapshot-gap rules, but does not depend on USD prices.
Missing supply makes `total_supply` null.

Linked share-issuing deployments must represent the same logical share asset.
The current cross-chain groups (`gtusda`, `stgusda`, and `devusda2`) use
Aspen multichain pricing with summed share supply. Values are
not carried forward. Missing deployment metadata fails the request.
Membership and primary selection follow the current Admin registry.

This sums deployment TVLs; it does not reproduce the old Aera API's separate
asset-position valuation or include pending deposits held in provisioners.


## OpenAPI

````yaml GET /v1/vaults/slug/{slug}/timeseries
openapi: 3.1.0
info:
  title: Gauntlet API
  description: Gauntlet vault data and user positions API.
  contact:
    name: Gauntlet
    url: https://gauntlet.xyz
  license:
    name: ''
  version: 1.0.0
servers:
  - url: https://api.gauntlet.xyz
    description: Production
security: []
tags:
  - name: System
    description: Health checks and Prometheus metrics
  - name: TVL
    description: Aggregate live TVL
  - name: Strategies
    description: Curated strategy groupings with aggregate metrics
  - name: Vaults
    description: Vault listings, details, metrics, timeseries
  - name: Users
    description: Per-wallet position state and timeseries
  - name: Prices
    description: Token price lookups and historical timeseries
paths:
  /v1/vaults/slug/{slug}/timeseries:
    get:
      tags:
        - Vaults
      summary: Get vault history by slug
      description: >-
        Returns USD TVL and outstanding share supply summed across every
        currently linked deployment of an enabled logical vault, including
        hidden vaults. Uses UTC-aligned snapshots and timestamp pagination. A
        deployment contributes zero before its indexed creation time; after
        creation, missing snapshots or USD prices produce null TVL, never a
        partial sum. Does not carry values forward. Missing supply or a missing
        snapshot after deployment creation produces null total_supply,
        independent of USD price availability. APY and unit_price come from the
        Admin-selected primary deployment at the same timestamp, identified by
        meta.resolved_vault_id. Missing primary snapshots yield null primary
        metrics; APY respects Admin visibility. TVL is USD-only because
        deployment numeraires may differ; native TVL remains available on the
        primary/per-deployment endpoints. This is a sum of deployment TVLs, not
        the legacy asset-position valuation. Unknown or disabled slugs return
        404; incomplete deployment metadata returns 503.
      operationId: get_vault_timeseries_by_slug
      parameters:
        - name: slug
          in: path
          description: Admin-curated public vault slug
          required: true
          schema:
            type: string
        - name: start
          in: query
          description: 'Window start: ISO 8601 date or RFC 3339 timestamp.'
          required: false
          schema:
            type: string
        - name: end
          in: query
          description: 'Window end: ISO 8601 date or RFC 3339 timestamp.'
          required: false
          schema:
            type: string
        - name: next
          in: query
          description: Opaque cursor from previous `meta.next_cursor`.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: Page size (1–10000, default 1000).
          required: false
          schema:
            type: integer
            format: int64
        - name: order
          in: query
          description: 'Sort direction: `asc` (default) or `desc`.'
          required: false
          schema:
            type: string
        - name: granularity
          in: query
          description: 'Sampling granularity: `day` (default), `hour`, `week`, or `month`.'
          required: false
          schema:
            type: string
      responses:
        '200':
          description: Aggregate USD TVL and share supply with primary deployment metrics
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/VaultGroupTimeseriesResponse'
        '401':
          description: Missing or invalid auth
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Vault slug not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Invalid parameters
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Data source or vault curation unavailable
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    VaultGroupTimeseriesResponse:
      type: object
      required:
        - meta
        - data
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/VaultGroupTimeseriesPoint'
        meta:
          $ref: '#/components/schemas/TimeseriesMeta'
    ErrorResponse:
      type: object
      description: Standard error response envelope returned on 4xx/5xx
      required:
        - error
      properties:
        error:
          $ref: '#/components/schemas/ErrorBody'
    VaultGroupTimeseriesPoint:
      allOf:
        - $ref: '#/components/schemas/PrimaryVaultTimeseriesMetrics'
        - type: object
          required:
            - timestamp
            - tvl
          properties:
            timestamp:
              type: string
              format: date-time
            total_supply:
              type:
                - string
                - 'null'
              description: >-
                Outstanding shares summed across linked deployments. Null if an
                existing

                deployment has a missing snapshot or supply; independent of USD
                pricing.
            tvl:
              $ref: '#/components/schemas/CuratedTvl'
              description: >-
                Sum across all linked deployments. Null if an existing
                deployment

                has a missing snapshot or USD price; never a partial sum.
    TimeseriesMeta:
      type: object
      required:
        - request_id
        - refreshed_at
        - count
        - limit
      properties:
        count:
          type: integer
          format: int64
          description: Number of points in this response.
        end:
          type:
            - string
            - 'null'
          format: date-time
        limit:
          type: integer
          format: int64
          description: Page-size cap actually applied.
        next_cursor:
          type:
            - string
            - 'null'
          description: Set when more pages exist; pass back as `?next=`.
        partial_errors:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/PartialResponseError'
          description: Item-scoped failures isolated from an aggregate response.
        refreshed_at:
          type: string
          format: date-time
        request_id:
          type: string
        resolved_vault_id:
          type:
            - string
            - 'null'
          description: >-
            Primary deployment selected for deployment-local metrics by a slug

            route. The aggregate slug route still sums TVL and supply across
            deployments.

            Omitted when the deployment is already identified in the request
            path.
        start:
          type:
            - string
            - 'null'
          format: date-time
          description: Window bounds the response covers (echoes the request when set).
    ErrorBody:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code (e.g. `NOT_FOUND`, `UNAUTHORIZED`)
        details: {}
        message:
          type: string
          description: Human-readable error message
    PrimaryVaultTimeseriesMetrics:
      type: object
      description: |-
        Deployment-local metrics. Null when the primary has no snapshot at this
        timestamp; APY also respects the Admin visibility setting.
      properties:
        apy_30d:
          type:
            - number
            - 'null'
          format: double
        apy_7d:
          type:
            - number
            - 'null'
          format: double
        apy_90d:
          type:
            - number
            - 'null'
          format: double
        unit_price:
          type:
            - string
            - 'null'
          description: Numeraire-token units per share on the primary deployment.
    CuratedTvl:
      type: object
      description: |-
        USD amount on curated aggregates: decimal string, `null` when the
        pricing service is not configured.
      properties:
        usd:
          type:
            - string
            - 'null'
    PartialResponseError:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: Machine-readable error code for the isolated item failure.
        message:
          type: string
          description: Human-readable error message.
        resource_id:
          type:
            - string
            - 'null'
          description: Resource that failed inside the aggregate response, when known.

````