---
title: "Collection Insights"
method: GET
path: "/api/v1/collection/insights"
tags: ["Collection Insights"]
---

# Collection Insights

`GET /api/v1/collection/insights`

## 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/collection/insights`
- Auth: HTTP bearer

Aggregated insight lenses over the caller's saved collection.

Every top-level block is independently nullable — a lens failure degrades
that block to null, never a 500.

## Response `200`

Successful Response

- CollectionInsightsResponse
  - `as_of` string, required
  - `totals` InsightsTotals
    - `piece_count` integer, required
    - `anchor_value_usd` number, required
    - `current_value_usd` number, required
    - `currency` string
  - `percentile` InsightsPercentile
    - `rank_percent` integer, required
    - `sample_size` integer, required
    - `distribution_date` string, required
    - `basis` string
  - `superlatives` InsightsSuperlative[], nullable
    - `species` string, required
    - `your_max_usd` number, required
    - `community_max_usd` number, required
    - `is_community_high` boolean, required
    - `scope` string
  - `composition` InsightsCompositionEntry[], nullable
    - `species` string, required
    - `count` integer, required
    - `total_value_usd` number, required
    - `share_pct` number, required
  - `movement` InsightsMovement
    - `portfolio_change_7d_pct` number, nullable
    - `portfolio_change_30d_pct` number, nullable
    - `market_change_7d_pct` number, nullable
    - `market_change_30d_pct` number, nullable
    - `per_species` InsightsSpeciesMovement[]
      - `species` string, required
      - `annual_trend_fraction` number, nullable
      - `change_7d_pct` number, nullable
      - `change_30d_pct` number, nullable
      - `confidence` string, nullable
  - `gaps` InsightsGaps
    - `notable_missing` InsightsMissingSpecies[], required
      - `species` string, required
      - `category` string, required
      - `annual_trend_fraction` number, nullable
      - `change_30d_pct` number, nullable
    - `birthstone` InsightsBirthstone, required
      - `owned_months` integer[], required
      - `missing_months` integer[], required
      - `completion_pct` integer, required
  - `metals` InsightsMetalSpot[], nullable
    - `metal` string, required
    - `spot_usd_oz` number, required
    - `change_7d_pct` number, nullable
    - `change_30d_pct` 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)