# describe_dimension_value

> Describe an ID

**Call:** `GET /v1/dimensions/{dimension}/{id}`  
**Price:** Uses credits (see each response's `X-Credits-Charged`)  
**Available:** soft launch  
**Contract:** https://api.gwix.ai/docs/reference

## What it's for

Explain what an ID means - its name, parent and attributes (for companies, the ultimate parent, ticker and industry).

## Use it when

- Before reporting a result, to name and define the thing measured.
- Checking whether an ID is retired (`status: retired` gives `successor_id`).

## Inputs

| Name | In | Type | Required | Meaning |
|---|---|---|---|---|
| `dimension` | path | string: role | sub_job_family | job_family | soc_occupation | job_level | company | industry | location | yes | Dimension to browse. `skill` is added after launch. |
| `id` | path | string | yes | Value ID in that dimension (e.g. `rol_8f3k2`, `cmp_4qz71`, `5413`, `mtr_35620`). |
| `classifications` | query | list of string: gwix_role | onet_soc | soc_2018 | soc_2010 | isco_08 | esco | naics | isic_4 |  | Extra classification codes to include for each value. Each extra system uses additional credits. |

Headers: `GWIX-Agent-Id`, `GWIX-On-Behalf-Of`.

## What comes back

`id`, `name`, `status`, `parent`, `level`, `country`, `ticker`, `classifications`, `dimension`, `successor_id`, `definition`, `aliases`, `job_family`, `sub_job_family`, `roles_count`, `typical_job_levels`, `company`, `location`, `industry`, `meta`.

## Rules

**Identify your agent.** Send `GWIX-Agent-Id` on every call (register once with `register_agent`). Unidentified keys get reduced limits and are refused after 10 minutes.

## Notes

- Roles show their sub-job family and job family; companies show the ultimate parent, ticker and primary 4-digit NAICS; locations show their parent and level.
- `classifications=soc_2018` adds a role's SOC 2018 occupation.

## When it doesn't work

| Status | What to do |
|---|---|
| 401 | Send a valid API key (`Authorization: Bearer ...`). |
| 402 | Not enough credits. The body lists packs and plans that would cover it. |
| 403 | Not allowed for this key or tier, a cap is reached, or the agent is unidentified; read `type` and `detail`. |
| 404 | No such ID. Use `lookup` or `list_dimension_values` to find valid IDs. |
| 429 | Rate or concurrency limit. Wait `Retry-After` seconds. |

## Next steps

[`crosswalk`](/context/crosswalk) · [`get_pay`](/context/get_pay)

## Example response

```json
{
  "dimension": "role",
  "id": "rol_29-1141.00",
  "name": "Registered Nurse",
  "status": "active",
  "definition": "Assesses patient health problems and needs, develops and implements nursing care plans, and maintains medical records.",
  "job_family": {
    "id": "jfm_nursing",
    "name": "Nursing"
  },
  "typical_job_levels": [
    {
      "id": "lvl_p2",
      "name": "P2"
    },
    {
      "id": "lvl_p3",
      "name": "P3"
    },
    {
      "id": "lvl_p4",
      "name": "Senior Professional"
    }
  ],
  "aliases": [
    "RN",
    "Staff Nurse",
    "Registered Nurse II"
  ],
  "classifications": [
    {
      "system": "soc_2018",
      "code": "29-1141",
      "name": "Registered Nurses",
      "match_type": "exact"
    },
    {
      "system": "isco_08",
      "code": "2221",
      "name": "Nursing professionals",
      "match_type": "broader"
    }
  ],
  "meta": {
    "request_id": "gwx_req_31ab",
    "taxonomy_version": "utb-1.0"
  }
}
```