companies.financials
Find SEC company filings by ticker or CIK, then read financial facts and revenue dimensions from a specific accession. Facts retain their exact period, unit, context and source. Segment, geographic, product and whole-company figures remain separate. An absent dimension is unknown, never inferred from consolidated revenue.
- operationId
- execute
Companies Financials - Source
- SEC EDGAR
- Typical credits
- 0 (free source)
- Search deadline
- 40 s server-side
- Paging
- local
- Availability
- ConfiguredChecked 2026-11-20 03:29 UTC

GET /v1/catalog (available). The timestamped snapshot describes configuration, not provider uptime or your account's enabled choices. Check the catalog with your own key before a call. Credits are explained under credits and limits.Request body
Body of POST /v1/capabilities/companies.financials/execute, JSON, validated against the CompaniesFinancialsRequest component of the public OpenAPI document. Defaults are applied server-side, so an omitted optional field behaves exactly as its default.
| Field | Description |
|---|---|
| companyobject | objectREQUIRED | SEC filer identity. Use CIK for an issuer without a listed ticker. |
| company.cikstringREQUIREDwhen option 1 | pattern ^[0-9]{1,10}$ |
| company.tickerstringREQUIREDwhen option 2 | pattern ^[A-Za-z0-9][A-Za-z0-9.-]{0,14}$ |
| view"filings" | "financials" | "revenue_breakdown" | Default "filings". |
| accessionstring | Required for a paginated fact view; public SEC accession number.pattern ^\d{10}-\d{2}-\d{6}$ |
| forms"10-K" | "10-Q" | "20-F" | "40-F" | "10-K/A" | "10-Q/A" | "20-F/A" | "40-F/A"[] | min items 1 · max items 8 · unique items |
| filed_fromstring | pattern ^\d{4}-\d{2}-\d{2}$ |
| filed_tostring | pattern ^\d{4}-\d{2}-\d{2}$ |
| numinteger | Default 5.min 1 · max 10 |
- Unknown keys are rejected with
400 invalid_request.
Rules the schema cannot express
Checked after schema validation; violations return 400 invalid_request with a plain message.
- A ticker must identify exactly one SEC filer; otherwise use the CIK.
filed_fromandfiled_tomust be valid ISO dates andfiled_frommust not followfiled_to.- Fact views (
financials,revenue_breakdown) requireaccession.
Examples
curl -s -X POST https://api.powerups-ai.store/v1/capabilities/companies.financials/execute \
-H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
-d '{"company":{"ticker":"NVDA"},"forms":["10-K"],"num":1}'Record fields
Each item in results[] carries record_id and title (contract, always present) and usually url and snippet. The other keys below are the documented tier: produced deterministically by this capability, omitted when the source has no value, checked against recorded source fixtures in our test suite, and published as the CompaniesFinancialsRecord component (all optional, extra keys allowed) so generated clients type them. The wire schema itself still validates only the base keys. Anything else comes from the provider and may change; see stability tiers.
| Key | Note |
|---|---|
| record_idstringALWAYS | Use it with record actions on POST /v1/follow-up. |
| titlestringALWAYS | Contract key. |
| urlstring | Contract key; usually present. |
| snippetstring | Contract key; usually present. |
| cikstringALWAYS | On every record. |
| issuerstring | Filings view. |
| accessionstringALWAYS | On every record. |
| formstring | Filings view. |
| filed_atstring | Filings view. |
| report_datestring | Filings view. |
| accepted_atstring | null | Filings view. |
| primary_documentstring | Filings view. |
| primary_urlstring | Filings view. |
| is_amendmentboolean | Filings view. |
| fact_idstring | Fact views. |
| valuenumber | string | Fact views. |
| unitobject | Fact views. |
| periodobject | Fact views. |
| dimensionsobject[] | Fact views. |
| sourcestringALWAYS | On every record. |
Caveats
financialsandrevenue_breakdowndetails may includecontinuation: { capability, body }, a typed next request for the paginated fact view.
Follow-ups
Paging: Whole result set held in the session; more is served locally and costs nothing.
{ "search_id": "…", "action": "more" } while has_more is true; tolerate an empty page and stop after a bounded number of pages.CompaniesFinancialsUpdateParams).Detail behaviour: Free provider lookup on first call; repeats are cached. details, financials and revenue_breakdown read SEC EDGAR directly at no charge; repeated calls are cached.
curl -s -X POST https://api.powerups-ai.store/v1/follow-up \
-H "Authorization: Bearer $AIPA_API_KEY" -H "Content-Type: application/json" \
-d '{"record_id":"rec_…","action":"details"}'details detail keys (owned, documented tier)
Filings view: the stored filing record with SEC index and primary-document URLs. Fact views: the stored fact with its accession and retrieval provenance. Built entirely by our code and published as the CompaniesFinancialsDetailsDetail component; the wire contract of detail stays untyped, extra keys may appear.
| Field | Description |
|---|
financials detail keys (owned, documented tier)
Selected reported facts of the accession with units, periods and dimensions. Built entirely by our code and published as the CompaniesFinancialsFinancialsDetail component; the wire contract of detail stays untyped, extra keys may appear.
| Field | Description |
|---|---|
| cikstringREQUIRED | — |
| accessionstringREQUIRED | — |
| sourcestringREQUIRED | — |
| source_documentsobjectREQUIRED | — |
| source_documents.instancestringREQUIRED | — |
| source_documents.labelsstring | — |
| content_sha256stringREQUIRED | — |
| retrieved_atstringREQUIRED | — |
| extraction_status"selected_reported_facts"REQUIRED | — |
| factsobject[]REQUIRED | At most 100; see fact_count and truncated. |
| facts[].entityobjectREQUIRED | — |
| facts[].entity.schemestringREQUIRED | — |
| facts[].entity.identifierstringREQUIRED | — |
| facts[].periodobjectREQUIRED | — |
| facts[].period.startstring | nullREQUIRED | — |
| facts[].period.endstring | nullREQUIRED | — |
| facts[].period.instantstring | nullREQUIRED | — |
| facts[].dimensionsobject (any keys)[]REQUIRED | — |
| facts[].conceptstringREQUIRED | — |
| facts[].labelstring | nullREQUIRED | — |
| facts[].fact_idstring | nullREQUIRED | — |
| facts[].context_idstringREQUIRED | — |
| facts[].unitobjectREQUIRED | — |
| facts[].unit.numeratorstring[]REQUIRED | — |
| facts[].unit.denominatorstring[]REQUIRED | — |
| facts[].valuestring | nullREQUIRED | — |
| facts[].decimalsstring | nullREQUIRED | — |
| facts[].precisionstring | nullREQUIRED | — |
| facts[].source_urlstringREQUIRED | — |
| facts[].duplicate_fact_idsstring | null[]REQUIRED | — |
| facts[].conflicting_valuesbooleanREQUIRED | — |
| fact_countintegerREQUIRED | min 0 |
| truncatedbooleanREQUIRED | — |
| continuationobjectREQUIRED | A typed next request for the paginated fact view of this accession. |
| continuation.capability"companies.financials"REQUIRED | — |
| continuation.bodyobject (any keys)REQUIRED | — |
| notesstring[]REQUIRED | — |
revenue_breakdown detail keys (owned, documented tier)
Revenue facts by segment, geography and product; overlapping views, not addable. Built entirely by our code and published as the CompaniesFinancialsRevenueBreakdownDetail component; the wire contract of detail stays untyped, extra keys may appear.
| Field | Description |
|---|---|
| cikstringREQUIRED | — |
| accessionstringREQUIRED | — |
| sourcestringREQUIRED | — |
| source_documentsobjectREQUIRED | — |
| source_documents.instancestringREQUIRED | — |
| source_documents.labelsstring | — |
| content_sha256stringREQUIRED | — |
| retrieved_atstringREQUIRED | — |
| extraction_status"selected_reported_facts"REQUIRED | — |
| factsobject[]REQUIRED | At most 100; see fact_count and truncated. |
| facts[].entityobjectREQUIRED | — |
| facts[].entity.schemestringREQUIRED | — |
| facts[].entity.identifierstringREQUIRED | — |
| facts[].periodobjectREQUIRED | — |
| facts[].period.startstring | nullREQUIRED | — |
| facts[].period.endstring | nullREQUIRED | — |
| facts[].period.instantstring | nullREQUIRED | — |
| facts[].dimensionsobject (any keys)[]REQUIRED | — |
| facts[].conceptstringREQUIRED | — |
| facts[].labelstring | nullREQUIRED | — |
| facts[].fact_idstring | nullREQUIRED | — |
| facts[].context_idstringREQUIRED | — |
| facts[].unitobjectREQUIRED | — |
| facts[].unit.numeratorstring[]REQUIRED | — |
| facts[].unit.denominatorstring[]REQUIRED | — |
| facts[].valuestring | nullREQUIRED | — |
| facts[].decimalsstring | nullREQUIRED | — |
| facts[].precisionstring | nullREQUIRED | — |
| facts[].source_urlstringREQUIRED | — |
| facts[].duplicate_fact_idsstring | null[]REQUIRED | — |
| facts[].conflicting_valuesbooleanREQUIRED | — |
| fact_countintegerREQUIRED | min 0 |
| truncatedbooleanREQUIRED | — |
| continuationobjectREQUIRED | A typed next request for the paginated fact view of this accession. |
| continuation.capability"companies.financials"REQUIRED | — |
| continuation.bodyobject (any keys)REQUIRED | — |
| notesstring[]REQUIRED | — |
Other record detail objects are provider-shaped: documented by observation, not by schema. Full follow-up semantics: follow-up.
Typed client
With types generated from the public document (see types, client and samples) the call is path-keyed and the body is checked at compile time:
const { data, error } = await client.POST("/v1/capabilities/companies.financials/execute", {
body: {
"company": {
"ticker": "NVDA"
},
"forms": [
"10-K"
],
"num": 1
},
});
if (error) throw new Error(`${error.error.code}: ${error.error.message}`);
for (const record of data.results) console.log(record.record_id, record.title);POST /v1/capabilities/companies.financials/execute
{
"company": {
"ticker": "NVDA"
},
"forms": [
"10-K"
],
"num": 1
}