API reference · Query

Fetch facts

POST/v1/facts:fetch

Typed facts for entities and fields, current or as of a (valid, known) pair.

scope: read
auth: Bearer key
operationId: FetchFacts
MCP tool: fetch_facts

Request body

application/json · FetchRequest · no other fields

Request body fields
Field	Type	Required	Limits	Holds
references	Reference[]	yes	1 to 100 items
as_of	AsOfRequest	no
fields	string[]	no	1 to 50 items
max_age_seconds	integer	no	1 to 315360000
mode	strict · standard · broad	no		Which items could be served. Each mode returns everything the one before it does.

Response

200 · FetchResponse. An answer, a partial answer, or typed abstentions.

Response fields
Field	Type	Holds
response_id	ResponseID	A response's ID. It replays and compares that exact response.
status	answered · partial · abstained	Whether there is an answer.
as_of	AsOf	When the answer applies (valid_at), and what the record held then (known_at).
mode	strict · standard · broad	Which items could be served. Each mode returns everything the one before it does.
preset	string · nullable	The key's preset, if any.
items	Item[]	The cited facts.
abstentions	Abstention[]	Why part of the question has no answer.
negative_results	NegativeResult[]	What was searched, and found nothing.
withheld	Withheld[]	Items left out, by reason and count.
attributions	Attribution[]	Text to repeat where you show the data.
meta	Meta	The policy version, the index versions, and the milliseconds the server took.
unresolved	Unresolved[]

Rate-limit headers

RateLimit-Limit: The bucket's size.
RateLimit-Remaining: Tokens left in it.
RateLimit-Reset: Seconds until it is full.

Problems

RFC 9457 application/problem+json. An abstention is not one of these: it is a 200.

Problems
HTTP	Code	When
400	INVALID_REQUEST	Malformed JSON, unknown fields, bad filter, limit exceeded
401	UNAUTHENTICATED	Missing, malformed, or revoked key
403	FORBIDDEN_SCOPE	The key lacks the required scope
413	PAYLOAD_TOO_LARGE	Body or upload over the limit
422	UNPROCESSABLE	Well-formed but semantically invalid
429	RATE_LIMITED	Rate limit or per-tenant model cap
500	INTERNAL, POLICY_ASSERT_FAILED, RESPONSE_UNREPLAYABLE	Server fault. The last two also alert
503	STORE_UNAVAILABLE, LLM_UNAVAILABLE, LOG_UNAVAILABLE	A dependency is down or a budget tripped
504	TIMEOUT	A deadline was exceeded

Sample

Request

POST /v1/facts:fetch
Content-Type: application/json

{
  "references": [
    {
      "identifier": {
        "scheme": "ofac_uid",
        "value": "3751"
      }
    }
  ],
  "fields": [
    "sanctions.listing_status",
    "sanctions.program"
  ],
  "mode": "standard"
}

Sample response · GET /v1/samples/fetch

{
  "abstentions": [],
  "as_of": {
    "known_at": "2026-10-28T14:34:53.180326Z",
    "valid_at": "2026-10-28T14:34:53.180326Z"
  },
  "attributions": [
    {
      "source_id": "ofac_sls",
      "text": "U.S. Department of the Treasury, Office of Foreign Assets Control (OFAC), Sanctions List Service"
    }
  ],
  "items": [
    {
      "authority": "official_database",
      "claim_type": "fact",
      "claimant": null,
      "conditions": null,
      "corroboration": [],
      "derived": null,
      "entity": {
        "id": "ent_06GR5VVHPDW2Q1HYD75X1W4YNM",
        "kind": "org",
        "name": "MOA NICKEL SA",
        "redirected_from": null
      },
      "evidence": {
        "passage_id": "pas_06GR5VVHPSZDV77D9BFJBCNB8G",
        "span": [
          0,
          1191
        ],
        "text": "<SanctionsEntry ID=\"3751\" ProfileID=\"3751\" ListID=\"1550\">\r\n      <EntryEvent ID=\"3751\" EntryEventTypeID=\"1\" LegalBasisID=\"91707\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <EntryEvent ID=\"1003751\" EntryEventTypeID=\"1\" LegalBasisID=\"92884\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <SanctionsMeasure ID=\"4293\" SanctionsTypeID=\"1705\">\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"126312\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"187865\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA-EO14404</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n    </SanctionsEntry>"
      },
      "fact_version_id": "fv_06GR5VVHQHSDX77J2HD9CC6QH4",
      "field": "sanctions.listing_status",
      "license": {
        "attribution": "U.S. Department of the Treasury, Office of Foreign Assets Control (OFAC), Sanctions List Service",
        "serve_policy": "full",
        "terms_url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/APIDocumentation.docx"
      },
      "origin": "shared",
      "places": null,
      "source": {
        "blob_sha256": "5c6a712b0f3865c123f9e1a4d840943f5c2f0da2b6283c8ae07d6a8933b0ea3f",
        "credibility": {
          "propaganda_risk": "low",
          "state_affiliated": false
        },
        "family": "us_treasury_ofac",
        "fetched_at": "2026-10-28T14:33:52.635305Z",
        "freshness": "stale",
        "id": "ofac_sls",
        "name": "OFAC Sanctions List Service (SDN and Consolidated non-SDN lists)",
        "parser_version": "2",
        "url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN_ADVANCED.XML"
      },
      "tier": "verified",
      "times": {
        "last_verified_at": "2026-10-28T14:33:52.635305Z",
        "publisher_released_at": "2026-10-21T00:00:00Z",
        "recorded_at": "2026-10-28T14:33:52.635305Z",
        "valid": {
          "from": "1995-05-23T00:00:00Z",
          "precision": "day",
          "to": null
        }
      },
      "value": {
        "list": "SDN List",
        "status": "listed",
        "measures": [
          "Block"
        ],
        "legal_bases": [
          "Cuban Assets Control Regulations (CACR)",
          "Executive Order 14404 (Cuba)"
        ]
      }
    },
    {
      "authority": "official_database",
      "claim_type": "fact",
      "claimant": null,
      "conditions": null,
      "corroboration": [],
      "derived": null,
      "entity": {
        "id": "ent_06GR5VVHPDW2Q1HYD75X1W4YNM",
        "kind": "org",
        "name": "MOA NICKEL SA",
        "redirected_from": null
      },
      "evidence": {
        "passage_id": "pas_06GR5VVHPSZDV77D9BFJBCNB8G",
        "span": [
          0,
          1191
        ],
        "text": "<SanctionsEntry ID=\"3751\" ProfileID=\"3751\" ListID=\"1550\">\r\n      <EntryEvent ID=\"3751\" EntryEventTypeID=\"1\" LegalBasisID=\"91707\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <EntryEvent ID=\"1003751\" EntryEventTypeID=\"1\" LegalBasisID=\"92884\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <SanctionsMeasure ID=\"4293\" SanctionsTypeID=\"1705\">\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"126312\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"187865\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA-EO14404</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n    </SanctionsEntry>"
      },
      "fact_version_id": "fv_06GR5VVHQHTW9CFS9DCX9R3YX4",
      "field": "sanctions.program",
      "license": {
        "attribution": "U.S. Department of the Treasury, Office of Foreign Assets Control (OFAC), Sanctions List Service",
        "serve_policy": "full",
        "terms_url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/APIDocumentation.docx"
      },
      "origin": "shared",
      "places": null,
      "source": {
        "blob_sha256": "5c6a712b0f3865c123f9e1a4d840943f5c2f0da2b6283c8ae07d6a8933b0ea3f",
        "credibility": {
          "propaganda_risk": "low",
          "state_affiliated": false
        },
        "family": "us_treasury_ofac",
        "fetched_at": "2026-10-28T14:33:52.635305Z",
        "freshness": "stale",
        "id": "ofac_sls",
        "name": "OFAC Sanctions List Service (SDN and Consolidated non-SDN lists)",
        "parser_version": "2",
        "url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN_ADVANCED.XML"
      },
      "tier": "verified",
      "times": {
        "last_verified_at": "2026-10-28T14:33:52.635305Z",
        "publisher_released_at": "2026-10-21T00:00:00Z",
        "recorded_at": "2026-10-28T14:33:52.635305Z",
        "valid": {
          "from": "2026-10-21T00:00:00Z",
          "precision": "day",
          "to": null
        }
      },
      "value": {
        "list": "SDN List",
        "program": "CUBA"
      }
    },
    {
      "authority": "official_database",
      "claim_type": "fact",
      "claimant": null,
      "conditions": null,
      "corroboration": [],
      "derived": null,
      "entity": {
        "id": "ent_06GR5VVHPDW2Q1HYD75X1W4YNM",
        "kind": "org",
        "name": "MOA NICKEL SA",
        "redirected_from": null
      },
      "evidence": {
        "passage_id": "pas_06GR5VVHPSZDV77D9BFJBCNB8G",
        "span": [
          0,
          1191
        ],
        "text": "<SanctionsEntry ID=\"3751\" ProfileID=\"3751\" ListID=\"1550\">\r\n      <EntryEvent ID=\"3751\" EntryEventTypeID=\"1\" LegalBasisID=\"91707\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <EntryEvent ID=\"1003751\" EntryEventTypeID=\"1\" LegalBasisID=\"92884\">\r\n        <Comment />\r\n        <Date CalendarTypeID=\"1\">\r\n          <Year>1995</Year>\r\n          <Month>5</Month>\r\n          <Day>23</Day>\r\n        </Date>\r\n      </EntryEvent>\r\n      <SanctionsMeasure ID=\"4293\" SanctionsTypeID=\"1705\">\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"126312\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n      <SanctionsMeasure ID=\"187865\" SanctionsTypeID=\"1\">\r\n        <Comment>CUBA-EO14404</Comment>\r\n        <DatePeriod CalendarTypeID=\"1\" YearFixed=\"true\" MonthFixed=\"true\" DayFixed=\"true\" />\r\n      </SanctionsMeasure>\r\n    </SanctionsEntry>"
      },
      "fact_version_id": "fv_06GR5VVHQHWAQATR0FWRTCDXKM",
      "field": "sanctions.program",
      "license": {
        "attribution": "U.S. Department of the Treasury, Office of Foreign Assets Control (OFAC), Sanctions List Service",
        "serve_policy": "full",
        "terms_url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/APIDocumentation.docx"
      },
      "origin": "shared",
      "places": null,
      "source": {
        "blob_sha256": "5c6a712b0f3865c123f9e1a4d840943f5c2f0da2b6283c8ae07d6a8933b0ea3f",
        "credibility": {
          "propaganda_risk": "low",
          "state_affiliated": false
        },
        "family": "us_treasury_ofac",
        "fetched_at": "2026-10-28T14:33:52.635305Z",
        "freshness": "stale",
        "id": "ofac_sls",
        "name": "OFAC Sanctions List Service (SDN and Consolidated non-SDN lists)",
        "parser_version": "2",
        "url": "https://sanctionslistservice.ofac.treas.gov/api/PublicationPreview/exports/SDN_ADVANCED.XML"
      },
      "tier": "verified",
      "times": {
        "last_verified_at": "2026-10-28T14:33:52.635305Z",
        "publisher_released_at": "2026-10-21T00:00:00Z",
        "recorded_at": "2026-10-28T14:33:52.635305Z",
        "valid": {
          "from": "2026-10-21T00:00:00Z",
          "precision": "day",
          "to": null
        }
      },
      "value": {
        "list": "SDN List",
        "program": "CUBA-EO14404"
      }
    }
  ],
  "meta": {
    "index_versions": {
      "ofac_sls": "01a182ef-71a0-7861-9595-c4ecfc82ba02"
    },
    "policy_version": 1,
    "server_ms": 4
  },
  "mode": "standard",
  "negative_results": [],
  "preset": null,
  "response_id": "resp_06GR5VVKG1VK1FDZBRNXMBAYG8",
  "status": "answered",
  "unresolved": [],
  "withheld": []
}