---
title: "Life expectancy & survival probabilities (SSA period life table)"
method: POST
path: "/v1/longevity"
tags: ["Retirement income"]
---

# Life expectancy & survival probabilities (SSA period life table)

`POST /v1/longevity`

## Request

- Base URL: `https://api.numeratica.com`
- URL: `https://api.numeratica.com/v1/longevity`
- Auth: one of:
  - HTTP bearer
  - API key in header `X-API-Key`

Life expectancy, the survival-probability curve, milestone probabilities (reaching 80/85/90/95/100), and the median age at death — from the SSA 2021 period life table. With a second life supplied, also returns the joint (first-death) and last-survivor life expectancies. A frailty multiplier scales the death probabilities. Deterministic.

## Request body

- LongevityRequest
  - `age` integer, required
  - `sex` 'male' | 'female', required
  - `health_adjustment` number: Frailty multiplier on death probabilities (<1 healthier, >1 frailer).
  - `second_age` integer: Second life (enables joint metrics).
  - `second_sex` 'male' | 'female'
  - `second_health_adjustment` number

## Response `200`

Longevity analysis

- LongevityResponse
  - `result_id` string
  - `engine_version` string
  - `inputs` LongevityRequest
    - `age` integer, required
    - `sex` 'male' | 'female', required
    - `health_adjustment` number: Frailty multiplier on death probabilities (<1 healthier, >1 frailer).
    - `second_age` integer: Second life (enables joint metrics).
    - `second_sex` 'male' | 'female'
    - `second_health_adjustment` number
  - `result` object
    - `life_expectancy` number: Expected remaining years.
    - `median_age_at_death` integer
    - `survival_curve` object[]
      - `age` integer
      - `probability` number
    - `milestones` object[]
      - `age` integer
      - `probability` number
    - `joint_life_expectancy` number: Years to the first death (only with a second life).
    - `last_survivor_life_expectancy` number: Years to the last death (only with a second life).
  - `disclaimer` string

## Other responses

- `400`: Invalid request
- `401`: Missing or invalid API key.
- `405`: Method not allowed
- `429`: The key's per-minute request budget is exceeded. Retry after the delay in the Retry-After header.
- `503`: A dependency (e.g. the key store) is temporarily unavailable, or the request exceeded its compute deadline. Retryable.

---

[API](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api.md) · [All operations](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/llms.txt) · [OpenAPI document](https://skmtc.dev/numeratica/apis/numeratica-financial-planning-calculations-api/revisions/075bcfbd1ebf?raw)