# get_provenance

> Where a metric comes from: publisher, licence, retrieval date, dataset version, method and lineage.

Where a metric comes from: publisher, licence, retrieval date, dataset version, method and lineage. Free (does not count against your plan).

**Counts against your plan:** no, free. **Read-only:** yes, nothing you send is stored or changes any data.

## Inputs

| Name | Type | Required | Default | Description |
|---|---|---|---|---|
| `metric_id` | `string` | yes | none | Metric id, e.g. 'rainfall_annual_mm' or 'crime_count:murder' |

## Caps

No row or area caps apply: the response is a fixed-size summary.

## Response

Every response also carries `citations`, `caveats` and `dataset_version` ([Citations](/docs/citations)).

| Field | Type | Description |
|---|---|---|
| `citations` | `object[]` |  |
| `caveats` | `string[]` |  |
| `dataset_version` | `string` |  |
| `metric` | `object` |  |
| `lineage` | `string[]` |  |
| `sources` | `object[]` |  |

**`metric`**

| Field | Type | Description |
|---|---|---|
| `id` | `string` |  |
| `label` | `string` |  |
| `description` | `string` |  |
| `unit` | `string` |  |
| `kind` | `string` |  |
| `spatial_aggregation` | `string` |  |
| `native_geographies` | `string[]` |  |
| `allowed_geographies` | `string[]` |  |
| `time_grain` | `string` |  |
| `time_rollups` | `object` |  |
| `period_format` | `string` |  |
| `first_period` | `string` |  |
| `last_period` | `string` |  |
| `available_ids` | `string[]` | Concrete ids for metric families |
| `family_members` | `object[]` |  |
| `caveats` | `string[]` |  |

**`sources[]`** (each item)

| Field | Type | Description |
|---|---|---|
| `source_id` | `string` |  |
| `name` | `string` |  |
| `publisher` | `string` |  |
| `url` | `string` |  |
| `licence` | `string` |  |
| `commercial_use` | `string` |  |
| `attribution` | `string` |  |
| `retrieved_at` | `string` |  |
| `dataset_version` | `string` |  |

**`metric.family_members[]`** (each item)

| Field | Type | Description |
|---|---|---|
| `id` | `string` |  |
| `label` | `string` |  |
| `is_aggregate` | `boolean` | SAPS roll-up category: never add it to its component offences |

## Examples

> **Fixture data**
>
> These responses were produced by the real tool against the synthetic test dataset (`fixture-2026.11.05`), so the numbers are illustrative, not real statistics. Production responses cite the real sources.

### Where a rainfall metric comes from

Request:

```json
{
  "metric_id": "rainfall_annual_mm"
}
```

Response: (lists shortened)

```json
{
  "citations": [
    {
      "source_id": "chirps_rainfall",
      "name": "[FIXTURE] CHIRPS v3.0 Monthly Rainfall",
      "publisher": "Climate Hazards Center, UC Santa Barbara",
      "url": "https://www.chc.ucsb.edu/data/chirps3",
      "licence": "CC-BY-4.0",
      "commercial_use": "yes",
      "attribution": "Funk et al., CHIRPS v3.0, Climate Hazards Center, UCSB.",
      "retrieved_at": "2026-11-05",
      "dataset_version": "fixture-2026.11.05"
    }
  ],
  "caveats": [
    "FIXTURE DATA: these numbers are synthetic test values, not real statistics. Do not use them for decisions.",
    "Satellite-derived estimate (CHIRPS ~5 km grid), averaged over the area; not a rain-gauge reading.",
    "rainfall_annual_mm values are modelled or satellite estimates."
  ],
  "dataset_version": "fixture-2026.11.05",
  "metric": {
    "id": "rainfall_annual_mm",
    "label": "Annual rainfall",
    "description": "Total rainfall in the calendar year (mm), averaged over the area. Areas combine by area-weighted mean, never by adding.",
    "unit": "mm",
    "kind": "mean",
    "spatial_aggregation": "area_weighted_mean",
    "native_geographies": [
      "ward",
      "local_municipality",
      "district",
      "province"
    ],
    "allowed_geographies": [
      "ward",
      "local_municipality",
      "district",
      "province"
    ],
    "time_grain": "year",
    "time_rollups": {},
    "period_format": "YYYY",
    "first_period": "2020",
    "last_period": "2025",
    "available_ids": [],
    "family_members": [],
    "caveats": [
      "Satellite-derived estimate (CHIRPS ~5 km grid), averaged over the area; not a rain-gauge reading."
    ]
  },
  "lineage": [
    "Raw files from Climate Hazards Center, UC Santa Barbara are retrieved by the ingest job and stored unchanged with retrieval date and checksum.",
    "Cleaned and conformed to the MDB 2026 ward/municipality/province and SAPS precinct geography in DuckDB (transform/).",
    "Stored in gold `fact` at native geography ['ward', 'local_municipality', 'district', 'province'] (methods: zonal_mean).",
    "Served by the semantic layer: combining areas uses area_weighted_mean."
  ],
  "sources": [
    {
      "source_id": "chirps_rainfall",
      "name": "[FIXTURE] CHIRPS v3.0 Monthly Rainfall",
      "publisher": "Climate Hazards Center, UC Santa Barbara",
      "url": "https://www.chc.ucsb.edu/data/chirps3",
      "licence": "CC-BY-4.0",
      "commercial_use": "yes",
      "attribution": "Funk et al., CHIRPS v3.0, Climate Hazards Center, UCSB.",
      "retrieved_at": "2026-11-05",
      "dataset_version": "fixture-2026.11.05"
    }
  ]
}
```

Provenance in this example: source `chirps_rainfall`, licence “CC-BY-4.0”, retrieved 2026-11-05, dataset_version `fixture-2026.11.05`.

## Errors

Errors read `<CODE>: <what went wrong>. Fix: <how to fix it>`. Shared codes are on the [Tool reference](/docs/tools) page.

| Request | Error |
|---|---|
| `{"metric_id": "no_such_metric"}` | `UNKNOWN_METRIC: Unknown metric 'no_such_metric'. Fix: Use one of ['population_total', 'population_density_km2', 'rainfall_monthly_mm', 'rainfall_annual_mm', 'crime_count:{category}', 'osm_school_count', 'osm_hospital_count', 'osm_clinic_count', 'osm_pharmacy_count', 'osm_police_station_count', 'osm_fuel_station_count', 'osm_supermarket_count', 'operating_revenue', 'operating_expenditure', 'property_rates_revenue', 'property_rates_revenue_per_capita', 'capital_budget', 'audit_outcome', 'unauthorised_irregular_fruitless_wasteful', 'cash_coverage_months', 'debtor_collection_rate']. Call describe_catalog for details.` |