---
title: "Spain unemployment rate (EPA Labour Force Survey)"
method: GET
path: "/api/v1/ine/unemployment"
tags: ["Statistical Agencies"]
---

# Spain unemployment rate (EPA Labour Force Survey)

`GET /api/v1/ine/unemployment`

National unemployment rate from the Encuesta de Poblacion Activa (EPA, operation 293), INE's official labour force survey. Returns the headline rate across both sexes and all age groups (EPA452434), quarterly, published ~25 days after quarter end.

## Query parameters

- `nult` integer — Number of most-recent quarterly observations.

## Response `200`

Quarterly unemployment rate observations (%).

- EnvelopeIneUnemploymentPayload
  - `data` IneUnemploymentPayload, required
    - `rate` IneSeries, required — A single INE time series with its observations.
      - `serie_id` string, nullable — INE series COD (e.g. IPC251856).
      - `name` string — Series name as published by INE.
      - `unit` string, nullable — Unit of measure label from `Unidad.Nombre`.
      - `scale` string, nullable — Scale label from `Escala.Nombre`.
      - `observations` IneObservation[] — Observations ordered by ascending date.
        - `date` string, required — Observation timestamp in ISO 8601 UTC (YYYY-MM-DDTHH:MM:SSZ), converted from INE `Fecha` with Madrid offset.
        - `value` union — Observation value from `Valor`. Null when the observation is confidential.
          - number
          - integer
        - `year` integer, nullable — Reference year (INE `Anyo`).
        - `period` string, nullable — Period label (e.g. 'M12' for December, 'QIV' for fourth quarter) from INE `Periodo`.
        - `data_type` string, nullable — Data type label (e.g. 'Final value', 'Provisional value') from INE `TipoDato`.
        - `confidential` boolean, nullable — True when the observation is flagged as secret by INE (`Secreto`).
      - `count` integer — Number of observations returned.
  - `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/revisions/a83e6a561bf2/schema)