GET /v1/statements/segmented-revenues

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

{
  "object": "segmented_revenue_series",
  "id": "segrev_example_geographic",
  "createdAt": "2026-02-20T00:00:00.000Z",
  "livemode": false,
  "entityId": "ent_example",
  "ticker": "EXAMPLE",
  "companyName": "Example Issuer, Inc.",
  "period": "annual",
  "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 product or geography revenue disclosures for one issuer, including capability state and trace references when the issuer provides the underlying detail.

Audience: application and coding agent.

Coverage and source scope

Use this route to analyze revenue splits the issuer actually disclosed in XBRL. Choose annual or quarterly cadence and, when useful, narrow to a product, geographic, or other reported dimension. Records retain the reported unit, period, segment hierarchy, capability status, and filing provenance; they are not a modeled revenue allocation. Preserve the returned accession, filing URL, and freshness fields before aggregating or presenting the result. See API conventions and freshness and source evidence.

Disclosure-aware revenue history

Supply one issuer identifier. Use period and segment_type to narrow the requested product or geography history, and use limit, segment_limit, and submission_file_limit to bound the work performed and the response size. The response reflects filing-derived disclosures, not a modelled revenue allocation. Check capability state, trace references, provenance, freshness, and materialization before comparing issuers or treating an absent product/geography row as zero.

Business breakdown workflow

Build disclosure-aware product and geography views.

Freshness and trust

Keep source timing and provenance visible in downstream use.

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-revenues?ticker=EXAMPLE&period=annual&segment_type=geographic&limit=6"

Example response

{
  "object": "segmented_revenue_series",
  "id": "segrev_example_geographic",
  "createdAt": "2026-02-20T00:00:00.000Z",
  "livemode": false,
  "entityId": "ent_example",
  "ticker": "EXAMPLE",
  "companyName": "Example Issuer, Inc.",
  "period": "annual",
  "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 an annual geographic 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 keep period and segment limits bounded for a predictable response
treat absent product or geography rows as undisclosed or unavailable, not as zero revenue
preserve capability state, trace references, provenance, freshness, materialization, requestId, and traceparent when handling a partial or transient result

GET /v1/statements/segmented-facts GET /v1/statements/share-float

​Coverage and source scope

​Disclosure-aware revenue history

​Related guides

Business breakdown workflow

Freshness and trust

​Canonical metadata

​Example request

​Example response

​About this example

​Give this prompt to your agent

​Failure posture

Coverage and source scope

Disclosure-aware revenue history

Related guides

Canonical metadata

Example request

Example response

About this example

Give this prompt to your agent

Failure posture