> ## Documentation Index
> Fetch the complete documentation index at: https://docs.secapi.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# GET /v1/statements/segmented-revenues

> Retrieve filing-derived product or geography revenue disclosures for one issuer, including capability state and trace references when the issuer provides t…

Retrieve filing-derived product or geography revenue disclosures for one issuer, including capability state and trace references when the issuer provides the underlying detail.

<Info>
  Audience: application and coding agent.
</Info>

## 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](/api-conventions) and [freshness and source evidence](/freshness-and-trust).

## 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.

## Related guides

<CardGroup cols={2}>
  <Card title="Business breakdown workflow" icon="git-branch" href="/business-breakdown">Build disclosure-aware product and geography views.</Card>
  <Card title="Freshness and trust" icon="shield-check" href="/freshness-and-trust">Keep source timing and provenance visible in downstream use.</Card>
</CardGroup>

## Canonical metadata

* `requestId`
* `traceparent`
* `provenance`
* `freshness`
* `materialization`

## Example request

<RequestExample>
  ```bash theme={null}
  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"
  ```
</RequestExample>

## Example response

<ResponseExample>
  ```json theme={null}
  {
    "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"
  }
  ```
</ResponseExample>

## 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

<Prompt>
  Use SEC API GET /v1/statements/segmented-revenues to retrieve filing-derived product or geography revenue disclosures for one issuer. Supply one issuer identifier, then use `period`, `segment_type`, and limits to bound the reporting history. Preserve segment dimensions, capability state, trace references, provenance, freshness, materialization, `requestId`, and `traceparent`; do not infer a product or geographic split when the issuer did not disclose one.
</Prompt>

## 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