---
title: "Earth-observation instrument catalog from WMO OSCAR/Space"
method: GET
path: "/api/v1/environment/oscar-wmo/instruments"
tags: ["Environment"]
---

# Earth-observation instrument catalog from WMO OSCAR/Space

`GET /api/v1/environment/oscar-wmo/instruments`

Return a filtered page of the WMO OSCAR/Space instrument catalog. The catalog covers 1,234 instruments spanning optical imagers, spectrometers, radar altimeters, radar scatterometers, GNSS receivers, radiometers, solar irradiance monitors, and more, each attributed to one or more providing agencies. Filters are applied client-side against Sugra's in-process catalog cache. Pass `measures_variable=<variable_slug>` to list only instruments that measure a given observation variable. Attribution: WMO OSCAR/Space (World Meteorological Organization).

## Query parameters

- `measures_variable` string, nullable — Variable slug filter - returns only instruments that measure this variable (e.g. `sea_surface_temperature`, `aerosol_optical_depth`). Derived by iterating the variables catalog.
- `q` string, nullable — Case-insensitive substring search across instrument acronym and full name.
- `limit` integer — Maximum number of records to return (1 to 500).
- `offset` integer — Zero-indexed offset into the filtered result list.

## Response `200`

Paginated list of instrument records matching the requested filters, with total and filtered counts.

- EnvelopeOscarInstrumentListPayload
  - `data` OscarInstrumentListPayload, required — Instrument catalog listing with pagination metadata.
    - `instruments` OscarInstrument[], required — Instrument records matching the requested filters, paginated.
      - `instrument_id` integer, nullable — Upstream numeric instrument identifier. Informational only - not accepted as a path parameter upstream.
      - `slug` string, nullable — URL-safe slug (primary key for detail lookup).
      - `acronym` string, nullable — Short display name or acronym (e.g. `3MI`, `ACRIM-III`).
      - `fullname` string, nullable — Full descriptive instrument name.
      - `providing_agency` string, nullable — Agency or agencies providing this instrument.
      - `agency_name` string, nullable — First participating agency name. Convenience alias for filtering and display.
      - `instrument_type` string, nullable — Instrument type classification (`Moderate-resolution optical imager`, `Radar scatterometer`, etc.).
      - `classification` string[], nullable — 3-level classification path (Earth observation instrument - class - subclass).
      - `wigos_subcomponent` object, nullable — Nested WIGOS subcomponent classification tree.
      - `satellites` OscarInstrumentSatellite[], nullable — Satellites this instrument flies or flew on.
        - `start_date` string, nullable — Flight start date in upstream freeform notation.
        - `end_of_life` string, nullable — Flight end-of-life date in upstream freeform notation.
        - `status` string, nullable — Flight status on this satellite.
        - `satellite_id` integer, nullable — Upstream numeric satellite identifier. Informational only; use `satellite_slug` for detail lookups.
        - `satellite_slug` string, nullable — Satellite slug (URL-safe identifier) - resolves via `/satellites/{slug}`.
        - `satellite_name` string, nullable — Satellite acronym or short name.
        - `satellite_fullname` string, nullable — Full descriptive satellite name.
      - `measurements` string[], nullable — Variables measured by this instrument (slugs). Derived from the upstream variables -> instruments mapping.
    - `total` integer, required — Total number of instruments across the entire catalog (before filtering).
    - `filtered` integer, required — Number of instruments after applying client-side filters.
    - `limit` integer, required — Page size requested by the client.
    - `offset` integer, required — Zero-indexed starting offset requested by the client.
    - `notes` string, nullable — Advisory notes about this response.
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/4c4530760ba1/schema)