GET /v1/filings/pension-benefit-schedule

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/filings/pension-benefit-schedule?ticker=VZ&filing_year=2022&target_year=2024"

{
  "requestId": "req_2ZK8Q1W9F4M6P7R3",
  "provenance": {
    "source": "sec",
    "accessionNumber": "0000320193-25-000079",
    "filingUrl": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927_htm.xml",
    "retrievedAt": "2026-03-17T00:00:00.000Z",
    "parserVersion": "2026-03-13.5",
    "rawSourceKey": "0000320193-25-000079"
  },
  "freshness": {
    "status": "fresh",
    "asOf": "2026-03-17T00:00:00.000Z",
    "sourcePublishedAt": "2025-10-31T00:00:00.000Z",
    "lagMs": 900000
  },
  "materialization": {
    "parserVersion": "2026-03-13.5",
    "materializationVersion": "datastream-3.0"
  }
}

Extract disclosed pension and retiree benefit payments for a target year

Audience: application and coding agent.

Coverage and source scope

Extract expected pension and retiree benefit payments for a requested target year from a selected issuer filing when the rendered source discloses a usable schedule. Supply an issuer, filing year, and target year; preserve the source accession and provenance. An unavailable result is not a zero payment or a complete benefits forecast.

Disclosure-aware schedule extraction

Supply one issuer selector plus the required filing_year and target_year; use accession_number when the disclosure vintage must be fixed. The route extracts a disclosed schedule from rendered filing tables, so preserve provenance and treat unavailable rows as unavailable disclosure rather than zero expected payments. See filing and source conventions before comparing schedule values across filing vintages.

Canonical metadata

requestId
traceparent
provenance
freshness
materialization

Example request

curl -X GET \
  -H "x-api-key: $SECAPI_API_KEY" \
  -H "secapi-version: 2026-03-19" \
  "https://api.secapi.ai/v1/filings/pension-benefit-schedule?ticker=VZ&filing_year=2022&target_year=2024"

Example response

{
  "requestId": "req_2ZK8Q1W9F4M6P7R3",
  "provenance": {
    "source": "sec",
    "accessionNumber": "0000320193-25-000079",
    "filingUrl": "https://www.sec.gov/Archives/edgar/data/320193/000032019325000079/aapl-20250927_htm.xml",
    "retrievedAt": "2026-03-17T00:00:00.000Z",
    "parserVersion": "2026-03-13.5",
    "rawSourceKey": "0000320193-25-000079"
  },
  "freshness": {
    "status": "fresh",
    "asOf": "2026-03-17T00:00:00.000Z",
    "sourcePublishedAt": "2025-10-31T00:00:00.000Z",
    "lagMs": 900000
  },
  "materialization": {
    "parserVersion": "2026-03-13.5",
    "materializationVersion": "datastream-3.0"
  }
}

Give this prompt to your agent

Failure posture

treat non-2xx responses as contract-aware failures, not free-form errors
preserve requestId and traceparent in logs and downstream reports
if provenance or freshness metadata is present, return it unchanged so trust is not lost in the handoff

​Coverage and source scope

​Disclosure-aware schedule extraction

​Canonical metadata

​Example request

​Example response

​Give this prompt to your agent

​Failure posture

Coverage and source scope

Disclosure-aware schedule extraction

Canonical metadata

Example request

Example response

Give this prompt to your agent

Failure posture