> This page is for API. > For clean Markdown of any page, append .md to the page URL. > For a complete documentation index, see https://docs.spreadspace.app/llms.txt. > For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.spreadspace.app/_mcp/server. # List registrant facts GET https://api.spreadspace.app/api/public/registrants/{registrant_id}/facts Lists the values a registrant reported for each named concept as a time series, across the filings the store holds that nothing has superseded: by period end, then concept, then the newest filing first. Each fact names its filing, unit, period and dimensions and the documents that print it, so every value leads back to its statement. `cadence`, `dimensions` and `prints` narrow the facts, `from` and `to` bound the period; more than 5000 matching facts is 400. Not paged. Needs a Market research subscription and `markets:read`. Requires the `markets:read` scope. Rate limit: 200 requests per minute per key (the `api` lane). Reference: https://docs.spreadspace.app/api/api-reference/registrants/list ## Authentication - `Authorization` header (bearer token, required) — Bearer token. Use `ss_live_…` for live data or `ss_test_…` for the sandbox (test mode). See [Authentication](https://docs.spreadspace.app/api/authentication). ## Request ### Path parameters - `registrant_id` (string, required) — The registrant's id: its SEC CIK, one to ten digits, with or without its leading zeros. ### Query parameters - `concepts` (list of string, optional) — The concepts to read, one `concepts` query parameter per concept, prefix included, 1 to 20 a call, each at most 200 characters. - `from` (date, optional) — The earliest period end, or instant, to keep, inclusive; no lower bound when absent. - `to` (date, optional) — The latest period end, or instant, to keep, inclusive; no upper bound when absent. - `cadence` (string, optional) — The facts to keep by period: `annual`, `quarterly`, `instant` or `all`; all when absent. - `dimensions` (string, optional) — The facts to keep by dimensions: `none`, the undimensioned facts alone, or `all`; none when absent. - `prints` (string, optional) — The prints to keep of each fact: `latest`, the newest filing's, or `all`; latest when absent. ### Headers - `SpreadSpace-Version` (string, optional) — Pin the API version, e.g. `2026-10-07`. Omit to get the latest. See [Versioning](https://docs.spreadspace.app/api/versioning). ## Response ### 200 OK - `data` (list of PublicFactView, required) - `has_more` (boolean, required) - `next_cursor` (string, optional, nullable) ## Errors ### 400 Bad Request Error Bad Request - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 401 Unauthorized Error Unauthorized: the bearer token or API key is missing or invalid. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 403 Forbidden Error Forbidden: authentication succeeded but the caller is not permitted to perform this action, for example an API key missing the required scope, an embed session reaching a loan it was not minted for, or a feature outside the workspace's plan. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 404 Not Found Error Not Found - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 429 Too Many Requests Error Too many requests: the rate limit was hit, or an idempotency-key replay is still in progress. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ### 500 Internal Server Error Internal server error: an unexpected failure. Quote the `request_id` in support tickets. A mutation sent with an `Idempotency-Key` replays this fault under that key rather than re-running; confirm the resource state before resending with a new key. - `error` (ApiErrorBody, required) — Inner body of the canonical API error envelope. ## Types ### PublicFactView One reported value of a concept in a registrant's filing, with the filing and the documents that carry it. - `fact_id` (string, required) — The fact's id, unique within its filing. - `accession` (string, required) — The SEC accession number of the filing the fact is reported in. - `concept` (string, required) — The tagged concept, prefix included. - `dimensions` (list of PublicFactDimension, required) — The context's dimensions, sorted by axis then member; empty when the fact is undimensioned. - `record_ordinals` (list of integer, required) — The ordinals of the filing's records that carry the fact, from one, as the filing's documents number them. - `document_ids` (list of string, required) — The ids of the filing's documents those records are, in the order of the ordinals; an ordinal with no document is left out. - `on_statement` (boolean, required) — True when a record other than a supporting table carries the fact. - `filing_date` (date, optional, nullable) — The date that filing was made; null when unknown. - `value` (double, optional, nullable) — The reported value; null when it is nil or does not read as a number. - `decimals` (integer, optional, nullable) — The reported decimals; null when absent or infinite. - `unit_kind` (string, optional, nullable) — The unit's kind, such as monetary; null when the fact carries no unit. - `currency` (string, optional, nullable) — The unit's currency code, such as USD; null when none. - `period_start` (date, optional, nullable) — The start of the period a duration fact covers; null for an instant fact. - `period_end` (date, optional, nullable) — The end of the period a duration fact covers; null for an instant fact. - `instant` (date, optional, nullable) — The date an instant fact stands at; null for a duration fact. ### ApiErrorBody Inner body of the canonical API error envelope. - `type` (enum, required) — Stable error type identifier, one of the values listed. Pattern-match on this value, not the human-readable message. A later version may add a value; treat one you do not know by its HTTP status. - Allowed values: `billing_required`, `business_email_required`, `conflict`, `counterparty_not_in_plan`, `cursor_expired`, `custom_visual_limit_exceeded`, `doc_too_large`, `embed_not_in_plan`, `embed_origin_not_allowed`, `embed_scope_exceeds_key`, `embed_scope_not_allowed`, `embed_session_binding_mismatch`, `embed_session_not_found`, `embed_token_expired`, `forbidden`, `geometry_plan_denied`, `html_upload_disabled`, `idempotency_in_progress`, `idempotency_request_mismatch`, `idempotency_response_too_large`, `insufficient_credits`, `insufficient_scope`, `internal_error`, `invalid_code`, `invalid_cursor`, `invalid_embed_token`, `invalid_include`, `invalid_limit`, `invalid_request`, `invalid_session_handle`, `invalid_version`, `key_expired`, `key_revoked`, `last_item`, `license_assigned`, `license_holder_has_license`, `license_none_free`, `license_reassign_window`, `licenses_assigned`, `markets_api_required`, `memo_locked`, `memo_not_locked`, `mfa_enrollment_required`, `mode_mismatch`, `not_found`, `payload_too_large`, `payment_failed`, `pii_claim_required`, `rate_limited`, `render_failed`, `request_cancelled`, `research_not_in_plan`, `resource_gone`, `same_origin_required`, `sandbox_missing`, `sandbox_organization`, `scope_not_in_product`, `scope_state_changed`, `session_handle_already_used`, `session_handle_expired`, `session_handle_revoked`, `spend_cap_reached`, `spread_already_finalized`, `spread_limit`, `spread_locked`, `spread_not_finalized`, `spread_not_locked`, `spread_not_ready`, `spread_template_limit_exceeded`, `spreads_not_in_plan`, `spreadsheet_upload_disabled`, `statement_mapping_not_in_plan`, `subscription_required`, `surface_limit_exceeded`, `test_key_remint_required`, `unauthorized`, `unknown_factor`, `unprocessable`, `usage_throttled`, `validation_failed` - `message` (string, required) — Human-readable error message. Subject to wording changes; do not parse. - `code` (string, optional) — A finer, stable identifier within `type`, on the errors that carry one; absent otherwise. Pattern-match on it like `type`. The upload presign answers `not_found` with `loan_not_found` and `invalid_request` with `borrower_loan_mismatch`. - `request_id` (string, optional, nullable) — Per-request correlation ID (matches `X-Request-ID` response header). Quote in support tickets. - `details` (map from string to string, optional, nullable) — Structured detail. Some error types populate documented keys in every environment: a version conflict (409) carries `current_version`, the version the resource is actually at, so the client can reload and re-apply. Free-form diagnostic detail beyond those keys appears in development environments only. An `insufficient_credits` 402 carries `balance_usd`, `reserved_usd`, `in_flight_docs`, `incoming_docs` and `per_doc_reservation_usd` as decimal strings. ### PublicFactDimension One dimension of a fact's context: an axis and the member the fact is reported for on it. - `axis` (string, required) — The axis, prefix included. - `member` (string, required) — The member on the axis, prefix included. ## Examples **Response** ```json { "data": [ { "fact_id": "f-0000412", "accession": "0009900077-26-000012", "concept": "us-gaap:Revenues", "dimensions": [], "record_ordinals": [ 2 ], "document_ids": [ "d0c0000000000000000000b6" ], "on_statement": true, "filing_date": "2026-03-02", "value": 418250000, "decimals": -3, "unit_kind": "monetary", "currency": "USD", "period_start": "2025-01-01", "period_end": "2025-12-31", "instant": null }, { "fact_id": "f-0000413", "accession": "0009900077-26-000012", "concept": "us-gaap:Revenues", "dimensions": [], "record_ordinals": [ 2 ], "document_ids": [ "d0c0000000000000000000b6" ], "on_statement": true, "filing_date": "2026-03-02", "value": 402110000, "decimals": -3, "unit_kind": "monetary", "currency": "USD", "period_start": "2024-01-01", "period_end": "2024-12-31", "instant": null } ], "has_more": false, "next_cursor": null } ``` **SDK Code** ```typescript import { SpreadSpace } from '@spreadspace/sdk'; const client = new SpreadSpace({ apiKey: process.env.SPREADSPACE_API_KEY! }); const facts = await client.registrants.facts('9900077', { concepts: ['us-gaap:Revenues'], cadence: 'annual' }); for (const fact of facts.data) console.log(fact.period_end, fact.value); ``` ```python import os from spreadspace import SpreadSpace client = SpreadSpace(api_key=os.environ["SPREADSPACE_API_KEY"]) facts = client.registrants.facts("9900077", concepts=["us-gaap:Revenues"], cadence="annual") for fact in facts["data"]: print(fact["period_end"], fact["value"]) ``` ```csharp using SpreadSpace; using var client = new SpreadSpaceClient(Environment.GetEnvironmentVariable("SPREADSPACE_API_KEY")); var facts = await client.Registrants.FactsAsync("9900077", ["us-gaap:Revenues"], cadence: "annual"); foreach (var fact in facts.Data) Console.WriteLine($"{fact.PeriodEnd} {fact.Value}"); ``` ```go package main import ( "fmt" "net/http" "io" ) func main() { url := "https://api.spreadspace.app/api/public/registrants/9900077/facts?concepts=%5B%22us-gaap%3ARevenues%22%5D&cadence=annual" req, _ := http.NewRequest("GET", url, nil) req.Header.Add("Authorization", "Bearer ") res, _ := http.DefaultClient.Do(req) defer res.Body.Close() body, _ := io.ReadAll(res.Body) fmt.Println(res) fmt.Println(string(body)) } ``` ```ruby require 'uri' require 'net/http' url = URI("https://api.spreadspace.app/api/public/registrants/9900077/facts?concepts=%5B%22us-gaap%3ARevenues%22%5D&cadence=annual") http = Net::HTTP.new(url.host, url.port) http.use_ssl = true request = Net::HTTP::Get.new(url) request["Authorization"] = 'Bearer ' response = http.request(request) puts response.read_body ``` ```java import com.mashape.unirest.http.HttpResponse; import com.mashape.unirest.http.Unirest; HttpResponse response = Unirest.get("https://api.spreadspace.app/api/public/registrants/9900077/facts?concepts=%5B%22us-gaap%3ARevenues%22%5D&cadence=annual") .header("Authorization", "Bearer ") .asString(); ``` ```php request('GET', 'https://api.spreadspace.app/api/public/registrants/9900077/facts?concepts=%5B%22us-gaap%3ARevenues%22%5D&cadence=annual', [ 'headers' => [ 'Authorization' => 'Bearer ', ], ]); echo $response->getBody(); ``` ```swift import Foundation let headers = ["Authorization": "Bearer "] let request = NSMutableURLRequest(url: NSURL(string: "https://api.spreadspace.app/api/public/registrants/9900077/facts?concepts=%5B%22us-gaap%3ARevenues%22%5D&cadence=annual")! as URL, cachePolicy: .useProtocolCachePolicy, timeoutInterval: 10.0) request.httpMethod = "GET" request.allHTTPHeaderFields = headers let session = URLSession.shared let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in if (error != nil) { print(error as Any) } else { let httpResponse = response as? HTTPURLResponse print(httpResponse) } }) dataTask.resume() ```