---
title: "Collection Analytics"
method: GET
path: "/api/v1/gems/collection/analytics"
tags: ["Gemstones"]
---

# Collection Analytics

`GET /api/v1/gems/collection/analytics`

## Request

- Base URL: `https://api.gemstoneaiapp.com` (the document declares no server; this is the origin it was published from)
- URL: `https://api.gemstoneaiapp.com/api/v1/gems/collection/analytics`
- Auth: HTTP bearer

GET /api/v1/gems/collection/analytics
Collection analytics: appreciation (Σ anchors vs Σ anchor × drift), top-5
7d gainers/losers (confidence-gated), value allocation by species, and
collection-vs-market 7d comparison. Empty collection → all nulls/empty
lists, 200. Reads of PR #53's tables (portfolio_snapshots,
watchlist_items) are guarded and degrade to per-gem math / nulls.

## Response `200`

Successful Response

- CollectionAnalyticsResponse
  - `appreciation` AppreciationBlock, required
    - `value_at_save` number, nullable
    - `value_now` number, nullable
    - `change_abs` number, nullable
    - `change_pct` number, nullable
  - `movers` AppSchemasChartDataMoversBlock, required
    - `gainers` MoverItem[], required
      - `gemstone_id` integer, required
      - `name` string, required
      - `current_value` number, required
      - `change_pct_7d` number, required
      - `change_abs_7d` number, required
    - `losers` MoverItem[], required
      - `gemstone_id` integer, required
      - `name` string, required
      - `current_value` number, required
      - `change_pct_7d` number, required
      - `change_abs_7d` number, required
  - `allocation` AllocationBlock, required
    - `by_species` SpeciesAllocation[], required
      - `species` string, required
      - `value` number, required
      - `pct` number, required
      - `count` integer, required
  - `vs_market` VsMarketBlock, required
    - `collection_change_pct_7d` number, nullable
    - `market_change_pct_7d` number, nullable

---

[API](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api.md) · [All operations](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/gemstoneaiapp/apis/gemstoneai-api/revisions/fcb441f55161?raw)