> ## Documentation Index > Fetch the complete documentation index at: https://docs.numi.sh/llms.txt > Use this file to discover all available pages before exploring further. # Get the segments of a filing by axis > Returns the segment breakdowns of one filing, one per XBRL axis: business, product or geography. Each axis has its rows, and `coverage_ratio` and `reconciliation` for how their revenue compares with the revenue that the filing reports. With `filing_id`, the response has the axes of that filing. Without `filing_id`, the response comes from the newest filing of `period_type` that has the axis in `axis`, or any axis when `axis` is not set. So when you set `axis` and the newest filing does not have that axis, you get the axis from the newest filing that has it. ## OpenAPI ````yaml GET /companies/{ref}/segments openapi: 3.1.0 info: title: numi API version: 0.1.0 summary: Company data for US SEC filers. description: > Segments by XBRL axis (business, product or geography), each axis checked against the revenue that the filing reports, and fundamentals as filed. Every success response has the form `{ "data": ..., "meta": { "request_id": "...", "as_of": "..." } }`, where `as_of` is the time of the response. Every error response has the form `{ "error": { "code": "...", "message": "..." }, "meta": { "request_id": "..." } }`, and some errors have more fields beside `code` and `message`. The `request_id` is also in the `x-request-id` response header. When you write to hello@numi.sh, quote it. servers: - url: https://api.numi.sh/v1 security: - ApiKey: [] - BearerKey: [] paths: /companies/{ref}/segments: get: summary: Get the segments of a filing by axis description: > Returns the segment breakdowns of one filing, one per XBRL axis: business, product or geography. Each axis has its rows, and `coverage_ratio` and `reconciliation` for how their revenue compares with the revenue that the filing reports. With `filing_id`, the response has the axes of that filing. Without `filing_id`, the response comes from the newest filing of `period_type` that has the axis in `axis`, or any axis when `axis` is not set. So when you set `axis` and the newest filing does not have that axis, you get the axis from the newest filing that has it. operationId: getSegments parameters: - $ref: '#/components/parameters/Ref' - name: axis in: query description: >- Returns this axis only. Without `axis`, the response has every axis of the filing. schema: $ref: '#/components/schemas/AxisName' - $ref: '#/components/parameters/PeriodType' - $ref: '#/components/parameters/FilingIdQuery' responses: '200': description: The filing and its axes. headers: x-request-id: $ref: '#/components/headers/RequestId' RateLimit-Remaining: $ref: '#/components/headers/RateLimitRemaining' content: application/json: schema: type: object required: - data - meta properties: data: type: object required: - company - filing - axes properties: company: $ref: '#/components/schemas/Company' filing: $ref: '#/components/schemas/Filing' axes: type: array items: $ref: '#/components/schemas/Axis' additionalProperties: false meta: $ref: '#/components/schemas/Meta' additionalProperties: false '400': $ref: '#/components/responses/BadRequest' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/SandboxRestricted' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' components: parameters: Ref: name: ref in: path required: true description: >- The company, as a ticker such as `MSFT` or `BRK.B`, or as `cik:` and the digits of its CIK (the SEC's Central Index Key), such as `cik:789019`. A ticker matches in upper or lower case, and `.` and `-` match each other, so `BRK.B` and `BRK-B` are the same company. schema: type: string pattern: ^([Cc][Ii][Kk]:[0-9]{1,10}|[A-Za-z0-9.-]{1,16})$ example: MSFT PeriodType: name: period_type in: query description: Annual filings (10-K, 20-F, 40-F) or quarterly ones (10-Q). schema: $ref: '#/components/schemas/PeriodTypeName' FilingIdQuery: name: filing_id in: query description: >- The id of one filing of the company, from `filings` in the response of `GET /companies/{ref}`. Without `filing_id`, the response comes from the newest filing of `period_type` that has the data asked for. schema: type: integer minimum: 1 maximum: 2147483647 schemas: AxisName: type: string enum: - business - product - geography description: >- The XBRL axis of a breakdown. `business` is the operating segments, `product` is the products and services, and `geography` is the regions. Company: type: object description: One SEC filer. required: - cik - ticker - tickers - name - exchange properties: cik: type: string pattern: ^[0-9]{10}$ description: The CIK, zero-padded to ten digits. example: '0000789019' ticker: type: - string - 'null' description: The primary ticker. example: MSFT tickers: type: array items: type: string description: Every ticker of the company. name: type: string example: MICROSOFT CORPORATION exchange: type: - string - 'null' example: Nasdaq additionalProperties: false Filing: type: object description: One extracted filing of the company. required: - id - form_type - filing_date - period_end - fiscal_year - fiscal_period - period_type - is_amendment - has_segments - has_note properties: id: type: integer description: The id of the filing, for `filing_id`. form_type: type: string description: The form, such as 10-K, 10-Q, 20-F, 40-F or an amendment of one. example: 10-K filing_date: type: string format: date period_end: type: - string - 'null' format: date description: The end of the period that the filing reports on. fiscal_year: type: - integer - 'null' fiscal_period: type: - string - 'null' description: FY for a year, Q1 to Q4 for a quarter. example: FY period_type: oneOf: - $ref: '#/components/schemas/PeriodTypeName' - type: 'null' is_amendment: type: boolean has_segments: type: boolean description: Whether the filing has at least one segment axis. has_note: type: boolean description: Whether the filing has a segment note. additionalProperties: false Axis: type: object description: One axis of one filing. allOf: - $ref: '#/components/schemas/AxisBody' unevaluatedProperties: false Meta: type: object description: The metadata of one success response. required: - request_id - as_of properties: request_id: $ref: '#/components/schemas/RequestId' as_of: type: string format: date-time description: The time of the response, in UTC. example: '2026-10-19T12:34:56.789Z' additionalProperties: false PeriodTypeName: type: string enum: - annual - quarterly default: annual RequestId: type: string pattern: ^req_[A-Za-z0-9_-]{16}$ description: The id of one request. example: req_Qm3xYb9Kd2LpR7wA AxisBody: type: object description: The fields of one axis of one filing. required: - axis - axis_qname - period_start - period_end - currency - revenue_concept - revenue_total - segment_revenue_sum - reconciling_revenue_sum - coverage_ratio - reconciliation - segments properties: axis: $ref: '#/components/schemas/AxisName' axis_qname: type: string description: The XBRL axis as filed. example: srt:ProductOrServiceAxis period_start: type: - string - 'null' format: date period_end: type: string format: date currency: type: - string - 'null' description: >- The currency code of the filing's own units for these figures, such as USD or TWD. It is the filing's label, not a converted or verified measure. example: USD revenue_concept: type: - string - 'null' description: The XBRL concept that the revenue figures come from. example: us-gaap:RevenueFromContractWithCustomerExcludingAssessedTax revenue_total: type: - number - 'null' description: The revenue that the filing reports for the company as a whole. segment_revenue_sum: type: - number - 'null' description: The revenue of the segment rows added up. reconciling_revenue_sum: type: - number - 'null' description: The revenue of the reconciling rows added up. coverage_ratio: type: - number - 'null' description: >- The segment and reconciling revenue over `revenue_total`, with at most six decimal places. Null when the filing reports no total, or when no row of the axis has revenue. reconciliation: type: string enum: - reconciled - over - under - unknown description: >- `reconciled` when `coverage_ratio` is from 0.95 to 1.05, both ends included, `over` when it is above 1.05, `under` when it is below 0.95, and `unknown` when there is no total or no row has revenue. segments: type: array items: $ref: '#/components/schemas/Segment' ErrorEnvelope: type: object description: The body of every error response. required: - error - meta properties: error: $ref: '#/components/schemas/ErrorBody' meta: type: object description: The metadata of one error response. required: - request_id properties: request_id: $ref: '#/components/schemas/RequestId' additionalProperties: false additionalProperties: false Segment: type: object description: >- One row of an axis, with its figures as filed. A figure that the filing does not report is null. required: - member - label - kind - revenue - operating_income - total_assets - depreciation_amortization - revenue_share properties: member: type: string description: The XBRL member of the row, as filed. example: msft:IntelligentCloudMember label: type: string description: A readable name made from the member. example: Intelligent Cloud kind: type: string enum: - segment - reconciling description: >- `segment` for a part of the business, a product line or a region, and `reconciling` for an amount between the sum of the parts and the total, such as an elimination or a corporate item. revenue: type: - number - 'null' operating_income: type: - number - 'null' total_assets: type: - number - 'null' depreciation_amortization: type: - number - 'null' revenue_share: type: - number - 'null' description: >- The revenue of the row over the revenue that the filing reports, with at most six decimal places. additionalProperties: false ErrorBody: type: object description: >- The error. Some errors have more fields beside the code and the message. A `rate_limit_exceeded` error has `retry_after` and `scope`, and a `sandbox_restricted` error has `sandbox_companies`, the tickers of the companies that you can read with a sandbox key. required: - code - message properties: code: type: string enum: - unauthorized - invalid_key - rate_limit_exceeded - bad_request - not_found - plan_required - sandbox_restricted - key_limit - conflict - internal_error - service_unavailable description: > A code for programs to branch on. - `unauthorized`: the request has no API key, or an account route has no session. - `invalid_key`: the key is not valid, or it was revoked. - `rate_limit_exceeded`: the account is at the request limit of its plan for the minute or the day, or the IP address is at its limit for the minute. - `bad_request`: a parameter is missing or wrong, or the body is not valid JSON or is too large. - `not_found`: nothing matches the request. - `plan_required`: the plan of the account does not include the endpoint, such as on-demand extraction on the sandbox plan. - `sandbox_restricted`: the request is for a company outside the sandbox, with a sandbox key. - `key_limit`: the account has as many active keys as its plan allows. - `conflict`: a checkout for an account that is on the Builder plan already, or the billing portal for an account with no subscription. - `internal_error`: the server failed. When you write to hello@numi.sh, quote the request id. - `service_unavailable`: the server is not configured for the feature, such as accounts, billing or bulk files. message: type: string description: >- A sentence that says what went wrong and, where it helps, what to do. additionalProperties: true headers: RequestId: description: >- The id of the request. It is also in `meta.request_id` of the body. When you write to hello@numi.sh, quote it. schema: $ref: '#/components/schemas/RequestId' RateLimitRemaining: description: >- The number of requests that the account has left today. REST and MCP calls count toward the same total, which is reset at midnight UTC. schema: type: integer minimum: 0 example: 238 responses: BadRequest: description: >- A parameter is missing or wrong, or the body is not valid JSON or is too large. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: bad_request message: 'limit: must be from 1 to 50' meta: request_id: req_Qm3xYb9Kd2LpR7wA Unauthorized: description: The request has no API key, or the key is not valid or was revoked. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: unauthorized message: >- The request has no API key. Send a numi API key in the X-API-Key header. meta: request_id: req_Qm3xYb9Kd2LpR7wA SandboxRestricted: description: >- The request is for a company outside the sandbox, with a sandbox key. `sandbox_companies` has the tickers of the companies that you can read with a sandbox key. On the Builder plan, you can read every company. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: sandbox_restricted message: >- TSLA is not in the sandbox. With a sandbox key, you can read 10 companies: MSFT, AAPL, NVDA, AMZN, GOOGL, META, NFLX, CVX, JPM and SONY. To read every company, upgrade to the Builder plan at https://numi.sh/account. sandbox_companies: - MSFT - AAPL - NVDA - AMZN - GOOGL - META - NFLX - CVX - JPM - SONY meta: request_id: req_Qm3xYb9Kd2LpR7wA NotFound: description: Nothing matches the request. headers: x-request-id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: not_found message: >- The API has no route for GET /v1/nothing. Find the routes of the API at https://docs.numi.sh. meta: request_id: req_Qm3xYb9Kd2LpR7wA RateLimited: description: >- The account is at the request limit of its plan for the minute or the day, or the IP address is at its limit for the minute. Wait the number of seconds in the `Retry-After` header. `scope` is `minute` or `day`, for the limit that was reached. headers: x-request-id: $ref: '#/components/headers/RequestId' Retry-After: description: The number of seconds to wait before the next request. schema: type: integer minimum: 1 example: 12 content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' example: error: code: rate_limit_exceeded message: >- The sandbox plan has a limit of 20 requests a minute. Retry in 12 seconds. retry_after: 12 scope: minute meta: request_id: req_Qm3xYb9Kd2LpR7wA securitySchemes: ApiKey: type: apiKey in: header name: X-API-Key description: A numi API key, sent in the `X-API-Key` header. BearerKey: type: http scheme: bearer description: 'A numi API key, sent as `Authorization: Bearer `.' ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.