> ## Documentation Index
> Fetch the complete documentation index at: https://docs.catchment.app/llms.txt
> Use this file to discover all available pages before exploring further.

# List metrics

> Catalogue of metrics this organisation can request, with stable key, label, description, unit, domain, source, nation coverage, supported geographies and period basis. Query parameters are ignored. This endpoint uses no credits.

## Catalogue scope

The catalogue is filtered by the organisation's API dataset and metric permissions. `geographies` controls which endpoint can read a key. `local_authority` keys can also be included in a postcode catchment request; they remain authority values in that response.

`period_basis` identifies source-period, current published, mixed population/supply, financial-year or monthly observations. It is not a claim that every dataset is current-year data. `nations: null` means no explicit nation restriction in the catalogue, within the API's overall Great Britain coverage; individual values may still be unavailable.

The static [metric catalogue](https://docs.catchment.app/api-reference/metric-catalogue.md) describes the current full-access set. This endpoint is the discovery contract for your own organisation. Query parameters are ignored. No credits are consumed.


## OpenAPI

````yaml /api-reference/openapi.json get /v1/metrics
openapi: 3.1.0
info:
  title: Catchment API
  version: 1.1.0
  description: >-
    Postcode catchment, H3 cell and local-authority metrics, with a discoverable
    metric catalogue, area mappings and organisation-level trial credits. Access
    must be explicitly enabled for the organisation. This reference describes
    the current implementation; availability depends on the deployed version.
servers:
  - url: https://api.catchment.app
security:
  - bearerAuth: []
tags:
  - name: Catchments
    description: Metric values for a catchment around a postcode.
  - name: Cells
    description: Metric values for a single H3 cell.
  - name: Area mappings
    description: Overlaps between statistical areas and H3 cells.
  - name: Metrics
    description: The metrics available to request.
  - name: Local authorities
    description: Fee and occupancy values for the reporting authority.
paths:
  /v1/metrics:
    get:
      tags:
        - Metrics
      summary: List metrics
      description: >-
        Catalogue of metrics this organisation can request, with stable key,
        label, description, unit, domain, source, nation coverage, supported
        geographies and period basis. Query parameters are ignored. This
        endpoint uses no credits.
      operationId: listMetrics
      responses:
        '200':
          description: >-
            Available metric definitions. The example is abbreviated to three
            entries; the actual response lists every metric permitted for the
            organisation.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/RequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/RateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/RateLimitRemaining'
            X-Credits-Used:
              $ref: '#/components/headers/CreditsUsed'
            X-Credits-Remaining:
              $ref: '#/components/headers/CreditsRemaining'
            Cache-Control:
              $ref: '#/components/headers/CacheControl'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MetricsResponse'
              example:
                request_id: 146b728a-d25b-4a42-a902-893e4f415d5f
                metrics:
                  - key: avg_income
                    label: Average Household income
                    description: ONS average income per household.
                    domain: affluence
                    unit: currency_gbp
                    source: ONS small area income estimates, FYE 2023
                    nations: null
                    geographies:
                      - catchment
                      - hex
                    period_basis: source_period
                  - key: avg_price
                    label: Average House Price (2024/5)
                    description: >-
                      Average residential sale price (2025 figures) from MH Land
                      Registry.
                    domain: affluence
                    unit: currency_gbp
                    source: HM Land Registry Price Paid Data
                    nations: null
                    geographies:
                      - catchment
                      - hex
                    period_basis: source_period
                  - key: la_occupancy_pct
                    label: Local authority occupancy
                    description: >-
                      Reported English older-adult residential and nursing
                      occupancy, excluding specialist beds. This is an authority
                      figure, not catchment occupancy.
                    domain: care
                    unit: percent
                    source: Capacity Tracker
                    nations:
                      - E92000001
                    geographies:
                      - local_authority
                    period_basis: latest_reporting_month
                credits:
                  used: 0
                  remaining: 1000
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/RateLimited'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  headers:
    RequestId:
      description: Identifies the request. Quote it when reporting a problem.
      schema:
        type: string
        format: uuid
    RateLimitLimit:
      description: Requests allowed per minute for this key.
      schema:
        type: integer
    RateLimitRemaining:
      description: Requests left for this key in the current minute.
      schema:
        type: integer
    CreditsUsed:
      schema:
        type: integer
        minimum: 0
        maximum: 50
      description: >-
        Credits used, once authenticated requests reach and complete credit
        accounting.
    CreditsRemaining:
      schema:
        type: integer
        minimum: 0
      description: >-
        Available organisation balance at settlement, excluding outstanding
        holds.
    CacheControl:
      schema:
        type: string
        const: no-store
      description: API JSON responses are not cached.
  schemas:
    MetricsResponse:
      type: object
      required:
        - request_id
        - metrics
        - credits
      properties:
        request_id:
          type: string
          format: uuid
        metrics:
          type: array
          items:
            $ref: '#/components/schemas/Metric'
        credits:
          $ref: '#/components/schemas/Credits'
    Metric:
      type: object
      required:
        - key
        - label
        - description
        - unit
        - domain
        - source
        - nations
        - geographies
        - period_basis
      properties:
        key:
          type: string
          description: The key to pass in `metrics`.
        label:
          type: string
        description:
          type:
            - string
            - 'null'
        unit:
          type:
            - string
            - 'null'
          description: >-
            Unit identifier supplied by the catalogue, such as count,
            currency_gbp, percent, pct, index or rank.
        domain:
          type:
            - string
            - 'null'
          description: Metric domain, including affluence, demographics, housing and care.
        source:
          type:
            - string
            - 'null'
          description: Where the data comes from.
        nations:
          type:
            - array
            - 'null'
          description: >-
            ONS codes of the nations the metric has values for. Null means all
            of Great Britain.
          items:
            type: string
        geographies:
          type: array
          items:
            type: string
            enum:
              - catchment
              - hex
              - local_authority
          minItems: 1
          description: >-
            Supported value geography. local_authority metrics can also be
            included in postcode catchment requests.
        period_basis:
          type: string
          enum:
            - source_period
            - current
            - source_population_and_current_supply
            - latest_financial_year
            - latest_reporting_month
          description: >-
            Temporal basis. source_period does not imply current-year data;
            source_population_and_current_supply combines source/projected
            demand with current published supply.
    Credits:
      type: object
      required:
        - used
        - remaining
      properties:
        used:
          type: integer
          minimum: 0
          maximum: 50
          description: >-
            Credits used by this request. One per distinct usable numeric metric
            returned by a successful metric request; zero for free endpoints or
            errors.
        remaining:
          type: integer
          minimum: 0
          description: >-
            Organisation credits available after settlement, excluding other
            in-flight reservations. Shared by all keys in the organisation.
    ErrorResponse:
      type: object
      required:
        - error
      properties:
        request_id:
          type: string
          format: uuid
          description: >-
            Present on requests handled by an endpoint. The unknown-path 404
            response has no request ID.
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              enum:
                - area_not_found
                - forbidden
                - internal_error
                - invalid_request
                - not_found
                - outside_coverage
                - postcode_not_found
                - rate_limited
                - unauthorized
                - credits_exhausted
            message:
              type: string
            unknown_metrics:
              type: array
              description: >-
                The metric keys that were not recognised, when that is the
                problem.
              items:
                type: string
            forbidden_metrics:
              type: array
              items:
                type: string
              description: Requested keys without dataset access.
            unsupported_metrics:
              type: array
              items:
                type: string
              description: Requested keys unsupported by this endpoint's geography.
            required_credits:
              type: integer
              minimum: 1
              maximum: 50
              description: >-
                Requested reservation that the available organisation balance
                cannot cover.
        credits:
          $ref: '#/components/schemas/Credits'
  responses:
    Unauthorized:
      description: The API key is missing, unknown or revoked.
      headers:
        WWW-Authenticate:
          schema:
            type: string
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            request_id: 4bc9eb08-0d69-4c6e-b226-1e66eda03bdc
            error:
              code: unauthorized
              message: >-
                A valid API key is required. Send it as an Authorization: Bearer
                header.
    Forbidden:
      description: The key is valid but organisation API access is disabled or expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            request_id: 0e2e47c8-e798-4247-a077-d6b4d66cb70f
            error:
              code: forbidden
              message: API access is not enabled for this organisation.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
    RateLimited:
      description: >-
        Per-key request limit reached in the current fixed calendar-minute
        window. The limit applies to free and metered requests. No credits are
        consumed.
      headers:
        Retry-After:
          description: Seconds until the next minute starts.
          schema:
            type: integer
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            request_id: c4c917f1-4162-47ac-b3d9-1642905491ba
            error:
              code: rate_limited
              message: Rate limit of 60 requests a minute reached.
    InternalError:
      description: >-
        The request or its accounting could not complete. Credits and rate-limit
        headers may be absent when accounting is unavailable. No metric data is
        sent before successful credit settlement.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            accountingFailure:
              summary: Illustrative server failure before credit accounting completes
              value:
                request_id: 9b8a7c6d-5e4f-4a3b-9c2d-1e0f9a8b7c6d
                error:
                  code: internal_error
                  message: >-
                    The request could not be completed. Quote the request id if
                    this keeps happening.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/RequestId'
        Cache-Control:
          $ref: '#/components/headers/CacheControl'
        X-RateLimit-Limit:
          $ref: '#/components/headers/RateLimitLimit'
        X-RateLimit-Remaining:
          $ref: '#/components/headers/RateLimitRemaining'
        X-Credits-Used:
          $ref: '#/components/headers/CreditsUsed'
        X-Credits-Remaining:
          $ref: '#/components/headers/CreditsRemaining'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: >-
        An API key created under **Account** > **Catchment API**. Keys start
        with `ck_`.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.