---
title: "Company facts"
method: GET
path: "/v1/facts"
---

# Company facts

`GET /v1/facts`

## Request

- Base URL: `https://api.turos.app`
- URL: `https://api.turos.app/v1/facts`
- Auth: one of:
  - API key in header `x-api-key`
  - HTTP bearer

Filter by concept, form, taxonomy, or unit. Requests default to the us-gaap taxonomy for 10-K and 10-Q filings. When neither taxonomy nor form is supplied and the us-gaap lookup is empty, the route automatically falls back to ifrs-full on 20-F and 6-K filings for foreign private issuers such as SAP, TM, SONY, and RIO.

## Query parameters

- `ticker` string
- `symbol` string
- `cik` string
- `tag` string
- `taxonomy` string
- `unit` string
- `form` string
- `formType` string
- `period` 'annual' | 'quarterly' | 'quarter' | 'q'
- `fy` integer
- `year` integer
- `fy_from` integer
- `fyFrom` integer
- `fy_to` integer
- `fyTo` integer
- `limit` integer
- `include` string
- `include_geographic_segments` boolean
- `geographic_segments` boolean
- `segment_limit` integer
- `segmentLimit` integer
- `submission_file_limit` integer
- `submissionFileLimit` integer
- `view` 'default' | 'agent'

## Response `200`

Successful response. Default view returns FactPointList; view=agent returns FactPointAgentList.

- union
  - FactPointList
    - `dataAsOf` string
    - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
    - `methodologyVersion` string
    - `materializationVersion` string
    - `object` 'list', required
    - `data` object[], required
      - `object` 'fact_point', required
      - `id` string, required
      - `createdAt` string, required
      - `livemode` boolean, required
      - `entityId` string, required
      - `ticker` string, nullable, required
      - `companyName` string, required
      - `taxonomy` string, required
      - `tag` string, required
      - `label` string, required
      - `unit` string, required
      - `value` number, required
      - `periodStart` string, nullable, required
      - `periodEnd` string, required
      - `filedAt` string, nullable, required
      - `form` string, nullable, required
      - `fy` number, nullable, required
      - `fp` string, nullable, required
      - `frame` string, nullable, required
      - `provenance` ResponseMetadata, required
        - `source` string, required
        - `sourceLabel` string
        - `sourceAgency` string
        - `canonicality` string
        - `fallbackPolicy` string
        - `accessionNumber` string, nullable, required
        - `filingUrl` string, uri, required
        - `acceptedAt` string, nullable
        - `retrievedAt` string, required
        - `parserVersion` string, required
    - `hasMore` boolean, required
    - `nextCursor` string, nullable, required
    - `responseMode` 'compact' | 'standard' | 'verbose', nullable
    - `include` string[], nullable
    - `requestId` string, required
    - `traceparent` string
    - `requestedTag` string, nullable
    - `resolvedTag` string, nullable
    - `aliasStrategy` string, nullable
    - `completeness` object
      - `source` 'xbrl_facts' | 'company_facts'
      - `observationsReturned` integer
      - `hasResolvedConcept` boolean
    - `freshness` FreshnessMetadata: Freshness of the record. For SEC filings, freshness measures the delay between SEC acceptance (`sourcePublishedAt`) and when the record became available in the API — not the age of the document. Statuses: `current` (recently published and available promptly), `archival` (an immutable historical document held in full; its availability delay is not a freshness signal), `degraded`/`stale` (a recently published filing that became available later than the freshness thresholds allow), `fresh` (continuously refreshed datasets recently observed at source), `unknown` (no timestamps). An old immutable filing is never `stale` simply because it was published long ago. `lagMs` is the publish-to-availability delay in milliseconds.
      - `status` 'fresh' | 'current' | 'archival' | 'stale' | 'degraded' | 'unknown', required
      - `asOf` string, required
      - `sourcePublishedAt` string, nullable
      - `lagMs` integer, nullable
    - `materialization` MaterializationMetadata
      - `parserVersion` string, required
      - `materializationVersion` string, required
    - `validation` ValidationStatus
      - `status` 'validated' | 'unvalidated' | 'degraded', required
      - `confidence` 'high' | 'medium' | 'low', nullable
      - `validatedAt` string, nullable
      - `validationPipeline` string, nullable
      - `exceptions` string[]
  - FactPointAgentList
    - `object` 'list', required
    - `data` object[], required
      - `object` 'fact_point', required
      - `tag` string, required
      - `label` string, required
      - `taxonomy` string, required
      - `unit` string, required
      - `value` number, required
      - `periodEnd` string, required
      - `fy` number, nullable
      - `fp` string, nullable
      - `form` string, nullable
      - `accessionNumber` string, nullable, required
      - `filingUrl` string, nullable, required
    - `hasMore` boolean, required
    - `nextCursor` string, nullable, required
    - `responseMode` 'compact' | 'standard' | 'verbose', nullable
    - `include` string[], nullable
    - `requestId` string, required

## Other responses

- `default`: Contract-aware error response

---

[API](https://skmtc.dev/turos/apis/turos-api.md) · [All operations](https://skmtc.dev/turos/apis/turos-api/llms.txt) · [OpenAPI document](https://skmtc.dev/turos/apis/turos-api/revisions/a68d3ec80a56?raw)