---
title: "Get Gemstone By Id"
method: GET
path: "/api/v1/market/data/{gemstone_id}"
tags: ["Market"]
---

# Get Gemstone By Id

`GET /api/v1/market/data/{gemstone_id}`

## 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/{gemstone_id}`
- Auth: none declared

Get complete details of a specific gemstone by its ID.

Returns comprehensive gemstone market data including:
- Basic information (variety, source, characteristics)
- Value drivers (carat, color, clarity, cut - with descriptions and star ratings)
- Market dynamics (supply, demand, trends)
- Market insights (up to 6 key facts)
- 2025 pricing details (min, avg, max, percentiles, YoY change) + computed UI fields (e.g., $K formats, YoY calc)
- Historical pricing (2020-2025 with event notes + $K for graph)
- Metadata (created_at, updated_at timestamps)

All UI computations (e.g., $K formatting, YoY %, graph-ready data) are done backend-only to reduce client load.
No variety-based queries; ID-only for security/scalability.

Args:
    gemstone_id: Unique integer ID of the gemstone record

Returns:
    GemstoneMarketDetailResponse: Complete gemstone details with pre-computed UI data

Raises:
    HTTPException 404: If gemstone with given ID is not found
    HTTPException 500: If database error occurs

## Path parameters

- `gemstone_id` integer, required

## Response `200`

Successful Response

- GemstoneMarketDetailResponse
  - `id` integer, required
  - `variety` string, required
  - `primary_source` string, nullable
  - `characteristics` string, nullable
  - `image_url` string, nullable
  - `value_drivers` object: Value drivers for carat, color, clarity, and cut
  - `market_dynamics` MarketDynamics, required
    - `supply_description` string, nullable
    - `total_global_supply` string, nullable
    - `in_circulation` string, nullable
    - `demand` string, nullable
    - `recent_trends` string, nullable
  - `market_insights` string[]: List of market insight facts
  - `pricing_2025` PricingDetails, required
    - `min` number, nullable
    - `avg` number, nullable
    - `max` number, nullable
    - `yoy_change_percent` number, nullable
    - `p10` number, nullable
    - `p25` number, nullable
    - `p50` number, nullable
    - `p75` number, nullable
    - `p90` number, nullable
    - `p95` number, nullable
    - `median_k` number, nullable: Median price in $K (p50 / 1000)
    - `computed_yoy_percent` number, nullable: Computed YoY % change vs. 2024 avg
    - `floor_k` number, nullable: Floor price in $K (min or p10 / 1000)
    - `premium_k` number, nullable: Premium price in $K (p75 / 1000)
    - `distribution_params` object, nullable: Params for bell curve: mean ($K), std ($K), skew hint
  - `historical_pricing` HistoricalPricing[]: Historical pricing from 2020-2024
    - `year` integer, required
    - `avg_price` number, nullable
    - `event_note` string, nullable
    - `price_k` number, nullable: Avg price in $K for graph y-axis
  - `created_at` string, date-time, required
  - `updated_at` string, date-time, required

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