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

# Reported Financials

> Look up a US public company's reported revenue, income, balance sheet figures or EPS by period, by its registry identifier.

Look up one reported financial figure of a US public company by its Central Index Key (CIK), the registrant number the US Securities and Exchange Commission assigns to every filer, as for Company Filings. `metric` is one of `revenue`, `net_income`, `operating_income`, `total_assets`, `total_liabilities`, `stockholders_equity`, `cash` or `eps_diluted`; `period` is `annual` (default) or `quarterly`. Returns the company name, the US GAAP tag and unit the figures come from, and one value per period, newest first, each with its calendar frame, start and end dates, fiscal year and period, the form that reported it, its filing date and accession number. Figures are as the company reported them in its filings, not adjusted or restated by anyone else; a later filing that restates a period replaces the earlier value. Looks up by identifier only: it does not search by company name or ticker. `periods` is empty when the company never reported the metric under its US GAAP tag. History is kept per series: Changes addresses one by the padded identifier, metric and period joined with colons (`0000320193:revenue:annual`); a call with a non-default `limit` is kept as a query.

## Authentication

Requires x402 payment in the `payment-signature` header.

## Request Body

**cik** `string` *required*

The registry identifier (CIK), for example 320193. Shorter numbers are padded with zeros. A CIK is 1 to 10 digits.

**metric** `string` *required*

Which reported figure to return. One of `revenue`, `net_income`, `operating_income`, `total_assets`, `total_liabilities`, `stockholders_equity`, `cash`, `eps_diluted`.

**period** `string`

Fiscal years or fiscal quarters. One of `annual`, `quarterly`. Defaults to `"annual"`.

**limit** `integer`

Most periods to return, newest first. From 1 to 20. Defaults to `5`.

<Snippet file="audit-context-params.mdx" />

## Response (200 OK)

Top-level envelope: `success` (boolean) and `data` (object). All fields below are nested under `data`.

**data.request\_id** `string`

Durable job ID for audit and lookup

**data.status** `string`

Job status: `completed`

**data.tool** `string`

Always `company_financials`

**data.result** `object`

The answer, described under Result below

**data.evidence** `object`

Where the answer came from and when

**data.evidence.source** `string`

The public body the data comes from. Always `US Securities and Exchange Commission`.

**data.evidence.source\_kind** `string`

`public` when the data comes from a public body, `commercial` otherwise

**data.evidence.retrieved\_at** `string`

When the lookup was made, as an ISO 8601 UTC time

**data.evidence.as\_of** `string`

The newest filing date among the returned periods; null when none were returned.

## Result

Nested under `data.result`.

**data.result.cik** `string`

The identifier, padded to 10 digits.

**data.result.company\_name** `string`

The filer's name as the source lists it; null when nothing was reported.

**data.result.metric** `string`

The metric asked for.

**data.result.tag** `string`

The US GAAP tag the figures came from.

**data.result.label** `string`

The source's label for the tag. `null` when the source gives no value.

**data.result.unit** `string`

USD, or USD/shares for `eps_diluted`. `null` when the source gives no value.

**data.result.periods** `object[]`

One value per period, newest `end` first; empty when the company never reported the tag.

**data.result.periods\[].frame** `string`

The source's calendar frame, for example CY2025 or CY2026Q2I; null when it framed none.

**data.result.periods\[].start** `string`

First day of the period, YYYY-MM-DD; null for a balance at a date.

**data.result.periods\[].end** `string`

Last day of the period or the balance date, YYYY-MM-DD.

**data.result.periods\[].value** `number`

The reported figure, in `unit`.

**data.result.periods\[].fiscal\_year** `integer`

The filer's fiscal year the filing covers. `null` when the source gives no value.

**data.result.periods\[].fiscal\_period** `string`

FY, Q1, Q2 or Q3. `null` when the source gives no value.

**data.result.periods\[].form** `string`

The form that reported this value, for example 10-K or 10-Q. `null` when the source gives no value.

**data.result.periods\[].filed** `string`

Date that filing was made, YYYY-MM-DD. `null` when the source gives no value.

**data.result.periods\[].accession** `string`

Accession number of that filing, with dashes. `null` when the source gives no value.

```bash cURL theme={null}
curl -X POST https://win.oneshotagent.com/v1/tools/lookup/company-financials \
  -H "Content-Type: application/json" \
  -H "payment-signature: <base64 x402 payment>" \
  -d '{
    "cik": "320193",
    "metric": "revenue",
    "limit": 2
  }'
```

```javascript JavaScript theme={null}
const response = await fetch("https://win.oneshotagent.com/v1/tools/lookup/company-financials", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "payment-signature": paymentProof,
  },
  body: JSON.stringify({
    "cik": "320193",
    "metric": "revenue",
    "limit": 2
  }),
});
```

```typescript SDK theme={null}
const result = await agent.tool('lookup/company-financials', {
  cik: '320193',
  metric: 'revenue',
  limit: 2
});
console.log(result.result);
console.log(result.evidence);
```

```json Response (200) theme={null}
{
  "success": true,
  "data": {
    "request_id": "uuid",
    "receipt_id": "rcpt_...",
    "status": "completed",
    "tool": "company_financials",
    "result": {
      "cik": "0000320193",
      "company_name": "Apple Inc.",
      "metric": "revenue",
      "tag": "RevenueFromContractWithCustomerExcludingAssessedTax",
      "label": "Revenue from Contract with Customer, Excluding Assessed Tax",
      "unit": "USD",
      "periods": [
        {
          "frame": "CY2025",
          "start": "2024-09-29",
          "end": "2025-09-27",
          "value": 416161000000,
          "fiscal_year": 2025,
          "fiscal_period": "FY",
          "form": "10-K",
          "filed": "2025-10-31",
          "accession": "0000320193-25-000079"
        },
        {
          "frame": "CY2024",
          "start": "2023-10-01",
          "end": "2024-09-28",
          "value": 391035000000,
          "fiscal_year": 2025,
          "fiscal_period": "FY",
          "form": "10-K",
          "filed": "2025-10-31",
          "accession": "0000320193-25-000079"
        }
      ]
    },
    "evidence": {
      "source": "US Securities and Exchange Commission",
      "source_kind": "public",
      "retrieved_at": "2026-10-21T12:00:00.000Z",
      "calls": [
        {
          "retrieved_at": "2026-10-21T12:00:00.000Z"
        }
      ],
      "as_of": "2025-10-31"
    }
  }
}
```

> [!NOTE]
>
> See [Pricing](https://docs.oneshotagent.com/pricing.md) for this tool's price. A wallet (x402) call receives it in the 402 quote before anything is charged; a call paid from prepaid credits is charged when the API accepts the request and answers `200`.

## Notes

* Results return inline. The finished job stays available at `/v1/requests/{request_id}`


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.