---
title: "Factor catalog"
method: GET
path: "/v1/factors/catalog"
---

# Factor catalog

`GET /v1/factors/catalog`

## Request

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

Return compact SEC API factor definitions, with trust and methodology metadata available on request.

## Query parameters

- `response_mode` 'compact' | 'standard' | 'verbose'
- `include` string

## Response `200`

Successful response

- FactorCatalog
  - `object` 'list', required
  - `data` FactorDefinition[], required
    - `dataAsOf` string
    - `freshnessStatus` 'fresh' | 'stale' | 'degraded' | 'unknown'
    - `methodologyVersion` string
    - `materializationVersion` string
    - `object` 'factor_definition', required
    - `responseMode` 'compact' | 'standard' | 'verbose': Projection used for this resource. compact is token-efficient for agents; standard and verbose retain fuller operational context.
    - `id` string, required
    - `key` string, required
    - `name` string, required
    - `category` 'market' | 'style' | 'macro' | 'sector' | 'industry' | 'country' | 'thematic', required
    - `description` string, required
    - `benchmarkSymbol` string, nullable
    - `equation` object
    - `orthogonalizedAgainst` string[]
    - `catalogStatus` 'launch_ready' | 'proof_gated_launch_candidate' | 'beta_short_history' | 'blocked_by_source' | 'intentionally_deferred', required: Public launch status for a catalog factor. launch_ready is only emitted when the retained launch metadata proof artifact is ready for the factor.
    - `sourceAvailabilityStatus` 'implemented' | 'data_source_available' | 'blocked_by_source' | 'intentionally_deferred', required
    - `launchUniverseStatus` 'launch_candidate' | 'beta_short_history' | 'blocked_by_source' | 'deferred_not_launch_scope', required
    - `launchClaimStatus` 'candidate_pending_history_freshness_proof' | 'not_claimed_beta_short_history' | 'not_claimed_source_blocked' | 'not_claimed_deferred_read_model', required
    - `launchParityCategory` 'basic' | 'style' | 'sector' | 'industry' | 'country' | 'custom_thematic' | 'out_of_scope_macro', required
    - `launchReadiness` FactorLaunchReadiness
      - `object` 'factor_launch_readiness', required
      - `status` 'launch_ready' | 'proof_gated_launch_candidate' | 'beta_short_history' | 'blocked_by_source' | 'intentionally_deferred', required: Public launch status for a catalog factor. launch_ready is only emitted when the retained launch metadata proof artifact is ready for the factor.
      - `proofGated` boolean, required
      - `proofReady` boolean, required
      - `observedProofStatus` 'ready' | 'degraded' | 'not_configured' | 'missing' | 'invalid' | 'stale', nullable, required
      - `proofObservedAt` string, date-time, nullable, required
      - `requiredProofArtifact` string, nullable, required
      - `requiredProofStatus` 'ready', nullable, required
      - `targetHistoryStartDate` string, date, nullable, required
      - `historyStartDateClaim` string, date, nullable, required
      - `betaReason` string, nullable, required
      - `exclusionReason` string, nullable, required
      - `claimPrerequisites` string[], required
    - `qualityProof` FactorQualityProof
      - `object` 'factor_quality_proof', required
      - `status` 'ready' | 'degraded' | 'not_available', required
      - `proofSource` string, nullable, required
      - `proofObservedAt` string, date-time, nullable, required
      - `rowLevelProofAvailable` boolean, required
      - `proofReady` boolean, required
      - `firstDate` string, date, nullable, required
      - `lastDate` string, date, nullable, required
      - `firstRequiredMarketDate` string, date, nullable, required
      - `latestMarketDay` string, date, nullable, required
      - `targetHistoryStartDate` string, date, nullable, required
      - `requiredHistoryStartDate` string, date, nullable, required
      - `shortHistoryExempt` boolean, required
      - `historyStartMarketDayLag` integer, nullable, required
      - `latestMarketDayLag` integer, nullable, required
      - `rowCount` integer, nullable, required
      - `distinctFactorDateCount` integer, nullable, required
      - `coveredMarketDateCount` integer, nullable, required
      - `expectedMarketDateCount` integer, nullable, required
      - `missingSessionCount` integer, nullable, required
      - `coveragePct` number, nullable, required
      - `methodologyVersion` string, nullable, required
      - `modelName` string, nullable, required
      - `methodologyUrl` string, nullable, required
      - `sourceMetadata` FactorQualityProofSourceMetadata, required
        - `latestAsOf` string, nullable, required
        - `latestSourcePublishedAt` string, nullable, required
        - `observedModelNameCount` integer, required
        - `observedModelNamesSample` string[], required
        - `nonStockBasketRowCount` integer, required
        - `metadataModelNames` string[], required
        - `metadataModelVersions` string[], required
        - `metadataMethodologyUrls` string[], required
      - `degradedReasons` string[], required
    - `expansionHints` string[]
    - `disclosures` string[]: Short product/legal disclosures for research-scenario outputs. Omitted on low-risk compact responses.
    - `provenance` ResponseMetadata
      - `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
    - `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
    - `sourceRights` SourceRightsMetadata
      - `source` string, required
      - `sourceLabel` string
      - `posture` 'public_safe' | 'contract_gated' | 'internal_only' | 'inventory_only' | 'review_required', required
      - `publicAvailability` 'public' | 'contract_gated' | 'internal_only' | 'inventory_only', required
      - `contractStatus` 'approved' | 'review_required' | 'restricted' | 'prohibited' | 'expired', required
      - `restrictions` string[]
      - `notes` string, nullable
    - `methodology` MethodologyMetadata
      - `id` string, required
      - `version` string, required
      - `summary` string, required
      - `confidence` 'high' | 'medium' | 'low', required
      - `launchState` 'experimental' | 'beta' | 'ga', required
      - `inputs` string[]
      - `validation` object
    - `revision` RevisionMetadata
      - `sourcePublishedAt` string, nullable
      - `retrievedAt` string, required
      - `vintageId` string, nullable
      - `revisedFrom` string, nullable
    - `degradedState` DegradedState
      - `code` string, required
      - `message` string, required
      - `retryable` boolean, required
      - `missingCapabilities` string[]
      - `fallbackUsed` string[]
  - `hasMore` boolean, required
  - `nextCursor` string, nullable, required
  - `responseMode` 'compact' | 'standard' | 'verbose': Projection used for this resource. compact is token-efficient for agents; standard and verbose retain fuller operational context.
  - `include` string[]
  - `requestId` string
  - `traceparent` string
  - `categories` 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)