---
title: "Get user position timeseries for a specific vault"
method: GET
path: "/v1/users/{wallet_address}/positions/{vault_id}/timeseries"
tags: ["Users"]
---

# Get user position timeseries for a specific vault

`GET /v1/users/{wallet_address}/positions/{vault_id}/timeseries`

## Request

- Base URL: `https://api.gauntlet.xyz`
- URL: `https://api.gauntlet.xyz/v1/users/{wallet_address}/positions/{vault_id}/timeseries`
- Auth: none declared

Returns historical value, cost basis, grouped PnL, 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.

## Path parameters

- `wallet_address` string, required
- `vault_id` string, required

## Query parameters

- `start` string
- `end` string
- `next` string
- `limit` integer
- `order` string
- `granularity` string

## Response `200`

Position timeseries

- UserPositionsTimeseriesResponse
  - `data` PositionTimeseriesPoint[], required
    - `cost_basis` AmountPair, required: Decimal-string metric paired across native (numeraire-token) and USD. `native` is always present; `usd` is JSON null when pricing is unavailable.
      - `native` string, required
      - `usd` string, nullable
    - `pnl` PnlBreakdown, required
      - `realized` AmountPair, required: Decimal-string metric paired across native (numeraire-token) and USD. `native` is always present; `usd` is JSON null when pricing is unavailable.
        - `native` string, required
        - `usd` string, nullable
      - `total` AmountPair, required: Decimal-string metric paired across native (numeraire-token) and USD. `native` is always present; `usd` is JSON null when pricing is unavailable.
        - `native` string, required
        - `usd` string, nullable
      - `unrealized` AmountPair, required: Decimal-string metric paired across native (numeraire-token) and USD. `native` is always present; `usd` is JSON null when pricing is unavailable.
        - `native` string, required
        - `usd` string, nullable
    - `roi_pct` RatioPair, required: JSON-number ratio paired across native (in-kind) and USD denominations. Null when event history is unavailable or cannot support ROI replay.
      - `native` number, double, nullable
      - `usd` number, double, nullable
    - `shares_owned` string, required: Shares currently held by the wallet at this timestamp.
    - `timestamp` string, date-time, required
    - `value` AmountPair, required: Decimal-string metric paired across native (numeraire-token) and USD. `native` is always present; `usd` is JSON null when pricing is unavailable.
      - `native` string, required
      - `usd` string, nullable
  - `meta` TimeseriesMeta, required
    - `count` integer, required: Number of points in this response.
    - `end` string, date-time, nullable
    - `limit` integer, required: Page-size cap actually applied.
    - `next_cursor` string, nullable: Set when more pages exist; pass back as `?next=`.
    - `partial_errors` PartialResponseError[], nullable: Item-scoped failures isolated from an aggregate response.
      - `code` string, required: Machine-readable error code for the isolated item failure.
      - `message` string, required: Human-readable error message.
      - `resource_id` string, nullable: Resource that failed inside the aggregate response, when known.
    - `refreshed_at` string, date-time, required
    - `request_id` string, required
    - `resolved_vault_id` string, nullable: 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` string, date-time, nullable: Window bounds the response covers (echoes the request when set).

## Other responses

- `401`: Missing or invalid auth
- `422`: Invalid cursor

## Changes

- **2026-09-30** `34bf11a7d24e`: 1 info
  - added the optional property `meta/resolved_vault_id` to the response with the `200` status
- **2026-08-27** `4452dcc4d7b3`: 1 info
  - added the optional property `meta/partial_errors` to the response with the `200` status
- **2026-08-08** `bd6a0a40d4fc`: 5 breaking, 1 info
  - the response property `data/items/roi_pct/native` became nullable for the status `200`
  - the response property `data/items/roi_pct/native` became optional for the status `200`
  - removed the required property `data/items/realized_pnl` from the response with the `200` status
  - removed the required property `data/items/total_pnl` from the response with the `200` status
  - …2 more

[Operation history](https://skmtc.dev/gauntlet/apis/gauntlet-api/changes/v1/users/:wallet_address/positions/:vault_id/timeseries/get.md)

---

[API](https://skmtc.dev/gauntlet/apis/gauntlet-api.md) - [All operations](https://skmtc.dev/gauntlet/apis/gauntlet-api/llms.txt) - [OpenAPI document](https://skmtc.dev/gauntlet/apis/gauntlet-api/revisions/34bf11a7d24e?raw)