# get_sunglasses_variant

Full record of one exact variant: every field with value, field_status, evidence excerpts, sources, check times and unknowns.

- REST: `GET https://sunglassesguides.com/api/v1/variants/{variant_id}` (OpenAPI operationId `get_sunglasses_variant`)
- MCP: tool `get_sunglasses_variant` on `https://sunglassesguides.com/mcp`
- Read-only: yes. It never changes anything outside this service.
- Market / units: US, USD, millimetres. Schema version 1.0.
- Support: implemented=true, data_covered=partial, externally_verified=false. 

## When to use

- You have a variant_id and need all facts and sources.

## When not to use

- You do not have a variant_id yet (use resolve_sunglasses or find_sunglasses).

## Input

Path parameters: `variant_id`. Query parameters: `expected_data_version`.

| Name | Type | Required | Range | Meaning |
|---|---|---|---|---|
| `variant_id` | string | yes |  | Stable variant_id from this catalog, e.g. returned by find_sunglasses or resolve_sunglasses. |
| `expected_data_version` | string | no |  | data_version returned by an earlier call. If the catalog changed since, the call fails with DATA_VERSION_CHANGED instead of mixing old and new facts. |


## Output

The standard envelope (see [REST conventions](https://sunglassesguides.com/docs/rest.md)): `request_id`, `success`, `schema_version`, `data_version`, `data_mode`, `generated_at`, `request`, `result`, `sources`, `freshness`, `cache`, `next_actions`, and `error` on failure.

status FOUND with the variant, or HTTP 404 NOT_FOUND for an unknown id.

`result.status` values: `FOUND`. `success:true` means the request was processed; it does not mean something matched.

## Sources and time

Each field carries `field_status`, `source_ids` and evidence excerpts; `sources[]` lists each cited source once with `retrieved_at`. `checked_at` is per record. See [freshness](https://sunglassesguides.com/docs/freshness.md).

## Permissions

Anonymous read-only trial without a key; optional API key for higher quotas. See [auth and quotas](https://sunglassesguides.com/docs/auth-and-quotas.md).

## Examples

### Success example

```sh
curl -sS https://sunglassesguides.com/api/v1/variants/rayban-rb2140f-8053672054682
```

```json
{
  "status": "FOUND",
  "variant": {
    "variant_id": "rayban-rb2140f-8053672054682",
    "brand": {
      "brand_id": "ray-ban",
      "entity_type": "brand",
      "name": "Ray-Ban",
      "official_site": null
    },
    "model": {
      "model_id": "rayban-original-wayfarer-lbf",
      "entity_type": "model",
      "name": "Original Wayfarer Low Bridge Fit",
      "manufacturer_model_code": "RB2140F",
      "aliases": [
        "Original Wayfarer Classic"
      ],
      "canonical_url": "https://sunglassesguides.com/sunglasses/ray-ban/original-wayfarer-low-bridge-fit-rb2140f",
      "family_note": "Standard-fit version is RB2140. Ray-Ban's US product-page text (title/meta) names it just 'Original Wayfarer Classic'; 'low bridge fit' appears only in some URL slugs and the RB..F code convention."
    },
    "display_name": "Original Wayfarer Classic Polished Black / G-15 Green 52-22",
    "size_label": "52-22",
    "unknown_fields": [
      "temple_length_mm",
      "lens_height_mm",
      "frame_width_mm",
      "manufacturer_fit_label",
      "bridge_fit",
      "adjustable_nosepads",
      "polarized",
      "vlt_percent",
      "lens_category",
      "lens_material",
      "uv_claim"
    ],
    "spec_freshness": {
      "checked_at": "2026-09-25T08:31:58Z",
      "status": "fresh",
      "age_seconds": 26697,
      "stale_reason": null
    }
  }
}
```

Markdown twin: https://sunglassesguides.com/variants/rayban-rb2140f-8053672054682.md

### Failure example

`curl -sS https://sunglassesguides.com/api/v1/variants/does-not-exist` returns HTTP 404 `NOT_FOUND`.

Stale version: `curl -sS 'https://sunglassesguides.com/api/v1/variants/rayban-rb2140f-8053672054682?expected_data_version=c0.o0'` returns HTTP 409 `DATA_VERSION_CHANGED` with `result.current_data_version`.

## Related tools

- [compare_sunglasses](https://sunglassesguides.com/docs/compare_sunglasses.md)
- [get_sunglasses_offers](https://sunglassesguides.com/docs/get_sunglasses_offers.md)