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

> Retrieve normalized SEC XBRL fact observations for an issuer and optional concept, taxonomy, unit, form, or fiscal-period filters.

Retrieve normalized SEC XBRL fact observations for an issuer and optional concept, taxonomy, unit, form, or fiscal-period filters.

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

## Agent mode

Pass `?view=agent` to receive the compact agent shape: concept, value, unit, and period fields plus lifted `accessionNumber` / `filingUrl` from provenance. Metadata envelopes are dropped. See [api conventions → response formats](/api-conventions) for the full `?view=` contract.

## Selecting comparable facts

Supply one issuer identifier. Omit `tag` to receive the service's common financial metrics, or pass an XBRL concept such as `Revenues`, `NetIncomeLoss`, or `PropertyPlantAndEquipmentNet` for a concept-specific series. Use `taxonomy`, `form`, `unit`, and fiscal-year filters to avoid mixing different concepts, reporting periods, or units.

With no explicit taxonomy or form, the route starts with `us-gaap` 10-K / 10-Q coverage and falls back to `ifrs-full` 20-F / 6-K when that lookup is empty for a foreign private issuer. Read `requestedTag`, `resolvedTag`, `aliasStrategy`, and `completeness` before treating a series as a like-for-like historical comparison.

## Related guides

<CardGroup cols={2}>
  <Card title="XBRL API guide" icon="braces" href="/seo/xbrl-api">Understand concepts, units, and filing-backed fact retrieval.</Card>
  <Card title="Freshness and trust" icon="shield-check" href="/freshness-and-trust">Interpret provenance and freshness metadata before publishing a result.</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/facts?ticker=EXAMPLE&tag=Revenues&form=10-K&limit=6"
  ```
</RequestExample>

## Example response

<ResponseExample>
  ```json theme={null}
  {
    "object": "list",
    "data": [
      {
        "object": "fact_point",
        "id": "fact_example_revenues_2025_fy",
        "createdAt": "2026-02-20T00:00:00.000Z",
        "livemode": false,
        "entityId": "ent_example",
        "ticker": "EXAMPLE",
        "companyName": "Example Issuer, Inc.",
        "taxonomy": "us-gaap",
        "tag": "Revenues",
        "label": "Revenue",
        "unit": "USD",
        "value": 123456789,
        "periodStart": "2025-01-01",
        "periodEnd": "2025-12-31",
        "filedAt": "2026-02-20",
        "form": "10-K",
        "fy": 2025,
        "fp": "FY",
        "frame": "CY2025",
        "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"
        }
      }
    ],
    "hasMore": false,
    "nextCursor": null,
    "requestedTag": "Revenues",
    "resolvedTag": "Revenues",
    "aliasStrategy": "exact",
    "completeness": {
      "source": "company_facts",
      "observationsReturned": 1,
      "hasResolvedConcept": true
    },
    "requestId": "req_2ZK8Q1W9F4M6P7R3",
    "traceparent": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
  }
  ```
</ResponseExample>

## About this example

This response uses a synthetic issuer and `example.com` URL to show a coherent annual revenue fact. It does not identify or claim a live SEC source.

## Give this prompt to your agent

<Prompt>
  Use SEC API GET /v1/facts to retrieve SEC XBRL fact observations for one issuer. Start with one issuer identifier, then add `tag`, `taxonomy`, `form`, `unit`, or fiscal-year filters only when the workflow needs a narrower series. Preserve the resolved concept, unit, period, accession number, filing URL, completeness, `requestId`, and `traceparent`; do not combine facts with different units or periods as though they were comparable.
</Prompt>

## Failure posture

* provide one issuer identifier and avoid conflicting `ticker` and `symbol` values
* do not substitute an unresolved concept or missing fact with zero; retain the returned concept-resolution and completeness fields
* compare only facts with compatible taxonomy, unit, form, and reporting-period context
* preserve `requestId` and `traceparent` when retrying a transient failure