GET /v1/statements/segmented-facts

curl -X GET -H "x-api-key: $SECAPI_API_KEY" -H "secapi-version: 2026-03-19" "https://api.secapi.ai/v1/statements/segmented-facts?ticker=EXAMPLE&metric=revenue&period=annual&segment_type=geographic&limit=6"

{
  "object": "segmented_fact_series",
  "id": "segfact_example_revenue_geographic",
  "createdAt": "2026-02-20T00:00:00.000Z",
  "livemode": false,
  "entityId": "ent_example",
  "ticker": "EXAMPLE",
  "companyName": "Example Issuer, Inc.",
  "period": "annual",
  "metric": "revenue",
  "capability": "supported",
  "records": [
    {
      "segmentAxis": "example:GeographicAxis",
      "segmentMember": "example:DomesticMember",
      "segmentLabel": "Domestic",
      "segmentType": "geographic",
      "axisFamily": "geography",
      "hierarchyDepth": 1,
      "isMostGranularSibling": true,
      "metricKey": "revenue",
      "taxonomy": "us-gaap",
      "tag": "Revenues",
      "unit": "USD",
      "value": 74000000,
      "periodStart": "2025-01-01",
      "periodEnd": "2025-12-31",
      "filingDate": "2026-02-20",
      "reportDate": "2025-12-31",
      "form": "10-K",
      "accessionNumber": "example-accession",
      "capability": "supported",
      "provenance": {
        "source": "example",
        "sourceLabel": "Illustrative response - not a live SEC filing",
        "accessionNumber": null,
        "filingUrl": "https://example.com/sec-filings/example-2025-10-k",
        "retrievedAt": "2026-02-20T00:00:00.000Z",
        "parserVersion": "example"
      }
    }
  ],
  "provenance": {
    "source": "example",
    "sourceLabel": "Illustrative response - not a live SEC filing",
    "accessionNumber": null,
    "filingUrl": "https://example.com/sec-filings/example-2025-10-k",
    "retrievedAt": "2026-02-20T00:00:00.000Z",
    "parserVersion": "example"
  },
  "requestId": "req_2ZK8Q1W9F4M6P7R3",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Retrieve filing-derived segment history for a required metric such as revenue or segment profit/loss, retaining disclosed dimensions, hierarchy, capability state, and trace references.

Audience: application and coding agent.

Coverage and source scope

Use this route to compare a disclosed segment metric across recent annual or quarterly filings. Select metric first, then use segment_type when the workflow needs a product, geographic, or other dimension. Rows preserve the issuer’s reported axes, members, units, reporting periods, and filing provenance; a missing segment or unsupported capability is not a zero value. Keep the returned accession, filing URL, and freshness fields with any analysis. See API conventions and freshness and source evidence.

Required metric and disclosure limits

Supply one issuer identifier and the required metric. Use period and segment_type to narrow the requested history, and use limit, segment_limit, and submission_file_limit to bound the returned filings, segment rows, and inspected SEC submission files. Segment dimensions and hierarchy reflect what the issuer disclosed. Read capability state and trace references before aggregating rows; an absent segment, unsupported metric, or unavailable hierarchy is not a zero value or a complete geographic/product split.

Business breakdown workflow

Use reported segment dimensions with explicit coverage caveats.

Coverage and depth

Check what source detail is available before building a comparison.

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/statements/segmented-facts?ticker=EXAMPLE&metric=revenue&period=annual&segment_type=geographic&limit=6"

Example response

{
  "object": "segmented_fact_series",
  "id": "segfact_example_revenue_geographic",
  "createdAt": "2026-02-20T00:00:00.000Z",
  "livemode": false,
  "entityId": "ent_example",
  "ticker": "EXAMPLE",
  "companyName": "Example Issuer, Inc.",
  "period": "annual",
  "metric": "revenue",
  "capability": "supported",
  "records": [
    {
      "segmentAxis": "example:GeographicAxis",
      "segmentMember": "example:DomesticMember",
      "segmentLabel": "Domestic",
      "segmentType": "geographic",
      "axisFamily": "geography",
      "hierarchyDepth": 1,
      "isMostGranularSibling": true,
      "metricKey": "revenue",
      "taxonomy": "us-gaap",
      "tag": "Revenues",
      "unit": "USD",
      "value": 74000000,
      "periodStart": "2025-01-01",
      "periodEnd": "2025-12-31",
      "filingDate": "2026-02-20",
      "reportDate": "2025-12-31",
      "form": "10-K",
      "accessionNumber": "example-accession",
      "capability": "supported",
      "provenance": {
        "source": "example",
        "sourceLabel": "Illustrative response - not a live SEC filing",
        "accessionNumber": null,
        "filingUrl": "https://example.com/sec-filings/example-2025-10-k",
        "retrievedAt": "2026-02-20T00:00:00.000Z",
        "parserVersion": "example"
      }
    }
  ],
  "provenance": {
    "source": "example",
    "sourceLabel": "Illustrative response - not a live SEC filing",
    "accessionNumber": null,
    "filingUrl": "https://example.com/sec-filings/example-2025-10-k",
    "retrievedAt": "2026-02-20T00:00:00.000Z",
    "parserVersion": "example"
  },
  "requestId": "req_2ZK8Q1W9F4M6P7R3",
  "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

About this example

This response is illustrative: the issuer, accession, segment members, and example.com URL are synthetic. It aligns a geographic annual revenue record with the request and does not claim a live SEC filing.

Give this prompt to your agent

Failure posture

provide one issuer identifier and the required metric; keep limit controls bounded for a predictable response
treat unsupported metrics, absent segment rows, or unavailable hierarchy as unavailable disclosure, not zero-valued segments
preserve capability state, trace references, provenance, freshness, materialization, requestId, and traceparent when handling a partial or transient result

​Coverage and source scope

​Required metric and disclosure limits

​Related guides

Business breakdown workflow

Coverage and depth

​Canonical metadata

​Example request

​Example response

​About this example

​Give this prompt to your agent

​Failure posture

Coverage and source scope

Required metric and disclosure limits

Related guides

Canonical metadata

Example request

Example response

About this example

Give this prompt to your agent

Failure posture