---
title: "Get Market Data"
method: GET
path: "/api/v1/market/data"
tags: ["Market"]
---

# Get Market Data

`GET /api/v1/market/data`

## 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/market/data`
- Auth: none declared

Get gemstone market data for the 'Market Benchmarks' listing page.

Open to all tiers (LNK-MKTTAB): the markets list is a retention surface;
monetization gates live on the scan path. The old 5-row free cap only
produced a broken-looking table (its client-side upsell was dead code)
while /market/index served all rows uncapped anyway.

Returns paginated, sorted variety-wise data with:
- variety: Gemstone name (sortable)
- avg/min/max: curated 2025 prices in raw dollars
- change: % change based on period (never null — 0.0 when unknowable)
- embedded live-index fields (index_value, change_1d/7d/30d_pct,
  confidence_tier, sparkline_7d, tier) so the table needs no second
  endpoint; null/[] for unindexed varieties

Period calculations (LNK-MKTCOHERE):
- 1month: live GemstoneAI index change_30d_pct — the same number the
  variety detail page leads with
- 6month: interpolated from mid-2024 to 2025 (legacy; app hides this tab)
- 1year: direct 2024-2025 YoY % from curated annual averages, clamped to
  the same +/-15% display cap as every other served change (LNK-MKTTAB)

Sorting: value sorts order by the number the Index column displays
(index_value, curated avg fallback); change sorts by the computed change
actually displayed for the selected period.

## Query parameters

- `period` '1month' | '6month' | '1year': Time period for calculating change percentage (matches UI tabs)
- `sort_by` 'variety_asc' | 'variety_desc' | 'avg_desc' | 'avg_asc' | 'change_desc' | 'change_asc': Sort results: variety_asc (default), variety_desc, avg_desc/avg_asc (by the displayed index value, curated avg fallback), change_desc/change_asc (by the displayed period change)
- `page` integer: Page number (starts from 1)
- `page_size` integer: Number of items per page

## Headers

- `authorization` string, nullable

## Response `200`

Successful Response

- MarketDataListResponse
  - `total` integer, required
  - `page` integer, required
  - `page_size` integer, required
  - `data` MarketDataVarietyResponse[], required
    - `id` integer, required
    - `variety` string, required
    - `avg` number, required
    - `change` number, required
    - `min` number, required
    - `max` number, required
    - `image_url` string, nullable
    - `index_value` number, nullable
    - `change_1d_pct` number, nullable
    - `change_7d_pct` number, nullable
    - `change_30d_pct` number, nullable
    - `confidence_tier` string, nullable
    - `explanation_headline` string, nullable
    - `sparkline_7d` number[]
    - `tier` string
  - `as_of` string, nullable

## Other responses

- `422`: Validation Error

---

[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)