> ## 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 user position timeseries for a specific vault > Returns historical value and ROI data for a single vault position. Default order is `asc` (oldest first, chart-friendly); pass `?order=desc` for newest-first list views. Cursor-paginated — pass `meta.next_cursor` back as `?next=` for the next page (cursor is bound to the order it was created with). Defaults to `granularity=day` (one UTC-midnight snapshot per day); `week` returns Monday 00:00 UTC snapshots, `month` returns first-of-month 00:00 UTC snapshots, and `hour` returns the raw hourly cadence. Default page size is 1000. ## OpenAPI ````yaml GET /v1/users/{wallet_address}/positions/{vault_id}/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: Vaults description: Vault listings, details, metrics, timeseries - name: Users description: Per-wallet position state and timeseries paths: /v1/users/{wallet_address}/positions/{vault_id}/timeseries: get: tags: - Users summary: Get user position timeseries for a specific vault description: >- Returns historical value and ROI data for a single vault position. Default order is `asc` (oldest first, chart-friendly); pass `?order=desc` for newest-first list views. Cursor-paginated — pass `meta.next_cursor` back as `?next=` for the next page (cursor is bound to the order it was created with). Defaults to `granularity=day` (one UTC-midnight snapshot per day); `week` returns Monday 00:00 UTC snapshots, `month` returns first-of-month 00:00 UTC snapshots, and `hour` returns the raw hourly cadence. Default page size is 1000. operationId: get_user_vault_position_timeseries parameters: - name: wallet_address in: path description: Ethereum wallet address required: true schema: type: string - name: vault_id in: path description: Vault identifier required: true schema: type: string - name: start in: query description: >- Window start: ISO 8601 date (`2026-01-01`, read as 00:00:00 UTC) or RFC 3339 timestamp (`2026-01-01T00:00:00Z`). required: false schema: type: string - name: end in: query description: >- Window end: ISO 8601 date (`2026-01-01`, read as 00:00:00 UTC) or RFC 3339 timestamp (`2026-01-01T00:00:00Z`). 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`. Day/week/month buckets start at 00:00 UTC; weeks start Monday and months start on the 1st. required: false schema: type: string responses: '200': description: Position timeseries content: application/json: schema: $ref: '#/components/schemas/UserPositionsTimeseriesResponse' '401': description: Missing or invalid auth content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' '422': description: Invalid cursor content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' components: schemas: UserPositionsTimeseriesResponse: type: object required: - meta - data properties: data: type: array items: $ref: '#/components/schemas/PositionTimeseriesPoint' 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' PositionTimeseriesPoint: type: object required: - timestamp - shares_owned - value - cost_basis - unrealized_pnl - realized_pnl - total_pnl - roi_pct properties: cost_basis: $ref: '#/components/schemas/AmountPair' description: >- Cumulative cost of held shares (`usd` uses per-event historical pricing). realized_pnl: $ref: '#/components/schemas/AmountPair' roi_pct: $ref: '#/components/schemas/RatioPair' description: >- ROI ratio (`native` is in-kind; `usd` is null when pricing unavailable). shares_owned: type: string description: Shares currently held by the wallet at this timestamp. timestamp: type: string format: date-time total_pnl: $ref: '#/components/schemas/AmountPair' unrealized_pnl: $ref: '#/components/schemas/AmountPair' value: $ref: '#/components/schemas/AmountPair' description: |- Position value at this timestamp (`native` = numeraire-token units, `usd` = `native` × historical USD price; null when unavailable). 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=`. refreshed_at: type: string format: date-time request_id: type: string 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 AmountPair: type: object description: >- Decimal-string metric paired across native (numeraire-token) and USD. `native` is always present; `usd` is JSON null when pricing is unavailable. required: - native properties: native: type: string usd: type: - string - 'null' RatioPair: type: object description: JSON-number ratio paired across native (in-kind) and USD denominations. required: - native properties: native: type: number format: double usd: type: - number - 'null' format: double ````