> ## Documentation Index > Fetch the complete documentation index at: https://doc.astreus.ai/llms.txt > Use this file to discover all available pages before exploring further. # List companies > List published companies. The response carries `total` and a per-country `countries[]` facet. ## OpenAPI ````yaml /openapi.json get /api/v1/companies openapi: 3.1.0 info: title: Astreus API version: 1.0.0 description: >- Astreus is a financial data terminal that turns the world's unstructured financial disclosure into structured, traceable data. It reads what companies, exchanges and central banks publish — annual and interim reports, SEC filings, results announcements, investor presentations, earnings calls, 8-Ks, regulator notices and policy text — across the United States, the Gulf (Tadawul, DFM, ADX, Boursa Kuwait, QSE), Japan, Taiwan, Korea, the UK and Europe, and serves it as data a program can trust: standardized financial statements (annual, quarterly, semiannual), segments and KPIs, the tables inside the notes, filing sections as text, investor decks page by page, earnings-call transcripts and audio, span-anchored observations, management guidance scored against outcomes, typed 8-K events, an attributed intraday news tape, insider and 13F ownership, a people registry, point-in-time macro series and central-bank text, benchmark, commodity and compute-price series, and a validated causal claim graph with scenario simulation. Every number carries the filing, page or passage it came from (`fact-source`), and nothing is served until it passes per-company validation gates. Coverage is published live: `GET /api/v1/landing/coverage` (no key) returns every market served with company counts, history depth, completeness and periods held per data type — ask it before answering "what do you cover?". `{id}` is a ticker, a numeric SEC CIK, or a platform key for a non-SEC issuer (XSAU000001) — the `cik` field of the company payload. Human-readable guides: https://doc.astreus.ai (coverage at /coverage, data catalog at /data-catalog). Tiers: `public` endpoints need no credentials. Everything else takes an **API key** — create one on the Developers page in the terminal (https://astreus.ai/developers) and send it as `X-API-KEY: pk_live_...` (or `Authorization: Bearer pk_live_...`). Signed-in terminal sessions may use their Cognito ID token instead. Rate limits and quotas are per plan (fixed UTC windows): Free — 30 req/min, 250 req/day; Build — 300 req/min, 100,000 req/month; Scale — custom. Build, Scale and prepaid credits are set up with sales (https://astreus.ai/contact), not self-serve. Responses carry RateLimit-*, X-Quota-* and, when credits pay, X-Billing-Source/X-Credits-Remaining-USD headers; a 429 carries `Retry-After` and a machine `code` of rate_limited or quota_exceeded (with sales_email). Not investment advice. See /terms. contact: email: saif@astreus.ai termsOfService: https://astreus.ai/terms servers: - url: https://astreus.ai security: [] tags: - name: Search & Meta description: Entity resolution and platform metadata. - name: Company Data description: Profiles, structure, leadership, calendars. - name: Financial Statements description: >- Standardized XBRL-derived statements — every line traceable to its filing via fact provenance. - name: SEC Filings description: >- The filing index and documents (SEC and exchange-published), parsed section text, and the tables inside the notes as gated grids and series. - name: 8-K Events description: Material events, typed by family, with extracted item text. - name: News description: >- The intraday news tape: filings, releases and licensed wires with source attribution, storylines and topics. - name: Transcripts & Calls description: Earnings-call transcripts, span-anchored observations, IR decks. - name: Guidance & Scorecards description: What management promised vs. what happened. - name: Ownership & Insiders description: 13F holders, Forms 3/4/5, the people registry. - name: Macro description: Point-in-time economic series and central-bank text. - name: Market Data description: Daily bars for stocks, benchmarks, commodities and compute. - name: Intelligence description: Narratives, the validated claim graph, scenario simulation. - name: Analytics description: Correlation and charting over any catalog series. paths: /api/v1/companies: get: tags: - Company Data summary: List companies description: >- List published companies. The response carries `total` and a per-country `countries[]` facet. operationId: get-list-companies parameters: - name: country in: query description: ISO-2 country code (US, SA, AE, JP, …). schema: type: string - name: sector in: query description: Filter by sector name. schema: type: string - name: search in: query description: Name, legal name or ticker contains. schema: type: string - name: scope in: query description: >- public (default) = listed companies; private = the private-company lane (XPRV keys); all. schema: type: string enum: - public - private - all default: public - name: sort in: query description: Sort column; default market-cap ranking. schema: type: string enum: - name - price - net_change - change - volume - market_cap - pe - name: direction in: query description: asc or desc (default). schema: type: string enum: - asc - desc default: desc - name: limit in: query description: 1–1000, default 100. schema: type: integer - name: offset in: query description: Default 0. schema: type: integer responses: '200': description: OK content: application/json: schema: type: object additionalProperties: true example: companies: - id: 3dc3b782-6b1c-455e-80ff-d4e8f07a09f3 name: NVIDIA CORP legal_name: NVIDIA CORP cik: '0001045810' ticker: NVDA exchange: N/A country_code: US sector: Technology industry: Semiconductors price: 214.72 change_percent: -0.982248 volume: 91591112 market_cap: 5200733120000 pe_ratio: 32.8821 logo_png_s3_key: logos/cik=0001045810/512.png website: https://www.nvidia.com brand_mark: >- https://cdn.brandfetch.io/nvidia.com/icon?c=1idQJ_8ukVnXwK_PLYs&fallback=404 share_classes: null - id: 33c210d5-7e67-436a-b240-96ba73998b12 name: Apple Inc. legal_name: Apple Inc. cik: '0000320193' ticker: AAPL exchange: N/A country_code: US sector: Technology industry: Consumer Electronics price: 309.35 change_percent: -0.6264 volume: 42216056 market_cap: 4519282704050 pe_ratio: 35.5166 logo_png_s3_key: logos/cik=0000320193/512.png website: https://www.apple.com brand_mark: >- https://cdn.brandfetch.io/apple.com/icon?c=1idQJ_8ukVnXwK_PLYs&fallback=404 share_classes: null - id: 9d155aca-6efd-4b57-aff2-188dc063a1d5 name: Alphabet Inc. legal_name: Alphabet Inc. cik: '0001652044' ticker: GOOGL exchange: N/A country_code: US sector: Communication Services industry: Internet Content & Information price: 344.82 change_percent: 1.21819 volume: 20779426 market_cap: 4200180710000 pe_ratio: 17.1994 logo_png_s3_key: logos/cik=0001652044/512.png website: https://about.google/ brand_mark: >- https://cdn.brandfetch.io/google.com/icon?c=1idQJ_8ukVnXwK_PLYs&fallback=404 share_classes: - symbol: GOOGL price: 344.82 change_percent: 1.21819 is_primary: true - symbol: GOOG price: 341.75 change_percent: 1.04967 is_primary: false total: 490 '400': description: Invalid parameter. content: application/json: schema: $ref: '#/components/schemas/Error' '401': description: Missing or invalid bearer token. content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Unknown company, country, symbol or resource. content: application/json: schema: $ref: '#/components/schemas/Error' '429': description: Rate limited. Honour Retry-After. content: application/json: schema: $ref: '#/components/schemas/Error' security: - apiKey: [] - cognitoIdToken: [] components: schemas: Error: type: object required: - error properties: error: type: string description: Human-readable message. code: type: string description: >- Stable machine code when present: unauthenticated, upgrade_required, rate_limited, quota_exceeded. enum: - unauthenticated - upgrade_required - rate_limited - quota_exceeded securitySchemes: apiKey: type: apiKey in: header name: X-API-KEY description: >- Astreus API key (pk_live_...), created on the Developers page in the terminal. Also accepted as `Authorization: Bearer pk_live_...`. x-default: pk_live_YOUR_KEY cognitoIdToken: type: http scheme: bearer bearerFormat: JWT description: >- Amazon Cognito ID token (token_use=id) for the Astreus user pool — the terminal's own session credential. API consumers should use an API key instead. ````