---
title: "List Guidance Outcomes"
method: POST
path: "/v0/filings/list_guidance_outcomes"
tags: ["V0", "Filings", "HAS_MCP_EQUIVALENT"]
---

# List Guidance Outcomes

`POST /v0/filings/list_guidance_outcomes`

## Request

- Base URL: `https://api.ultralayer.ai`
- URL: `https://api.ultralayer.ai/v0/filings/list_guidance_outcomes`
- Auth: HTTP bearer

Company guidance versus the reported actual.

## Request body

- GuidanceOutcomeListParams: Request body for POST /v0/filings/list_guidance_outcomes.
  - `start_timestamp` string, date-time, nullable: System timestamp; Inclusive ISO 8601
  - `end_timestamp` string, date-time, nullable: System timestamp; Inclusive ISO 8601; null=realtime
  - `limit` integer
  - `symbols` string[], nullable: Match any.
  - `metric_keys` string[], nullable: Match any.
  - `metric_key_exact_match` boolean: true: exact metric_keys, case-insensitive; false: case-insensitive substring. Ignored without metric_keys.
  - `metric_basis` string[], nullable: Match any.
  - `segments` string[], nullable: Match any. 'null' is consolidated.
  - `guided_period_type` string[], nullable: Match any.
  - `guided_fiscal_year` integer, nullable
  - `guided_fiscal_quarter` integer, nullable
  - `guided_period_end_from` string, date, nullable: Inclusive guided period-end date.
  - `guided_period_end_to` string, date, nullable: Inclusive guided period-end date.
  - `detail` 'full' | 'standard' | 'essential': essential:identity; standard:citable; full:all.
  - `outcomes` string[], nullable: Match any. Omit: resolved labels only.
  - `sort` 'timestamp' | 'outcome_abs': timestamp: newest actual first; outcome_abs: largest |score| first.

## Response `200`

Guidance outcomes at detail=full.

- GuidanceOutcome[]
  - `symbol` string, required: Listing symbol of the filer.
  - `company_name` string, nullable, required: Filer name.
  - `cik` integer, nullable, required: SEC CIK of the filer.
  - `timestamp` string, date-time, required: System timestamp of the outcome.
  - `source_timestamp` string, date-time, required: When the actual became public.
  - `metric_key` string, required: Normalized metric identity.
  - `metric_basis` 'gaap' | 'non_gaap' | 'unspecified', required: gaap, non_gaap, or unspecified.
  - `segment` string, nullable, required: Segment cut; null for consolidated guidance.
  - `guided_period_type` 'quarter' | 'fiscal_year' | 'half' | 'multi_year' | 'other', required: Kind of period being guided.
  - `guided_fiscal_year` integer, required: Filer fiscal year of the guided period.
  - `guided_fiscal_quarter` integer, nullable, required: Filer fiscal quarter of the guided period; null for a full year.
  - `guided_period_end_date` string, date, nullable, required: Calendar day the guided period ends.
  - `guidance_source_type` string, required: Document class the scored guide was issued from.
  - `actual_source_type` string, required: Document class the actual was reported in.
  - `outcome` 'significantly_exceeded' | 'exceeded' | 'in_line' | 'missed' | 'significantly_missed' | 'indeterminate', required: Judgment of the actual against the guide.
  - `rationale` string, required: Why this outcome label.
  - `guidance_quote` string, required: Stating sentence of the scored guide.
  - `actual_quote` string, required: Sentence or table row the actual was read from.
  - `value_type` 'range' | 'point' | 'floor' | 'ceiling' | 'approximate' | 'qualitative', required: Shape of the stated guide.
  - `value_form` 'absolute' | 'relative', required: absolute is a level; relative is a change vs a temporal base.
  - `value_low` number, nullable, required: Lower bound of the scored guide as stated.
  - `value_high` number, nullable, required: Upper bound of the scored guide as stated.
  - `value_midpoint` number, nullable, required: Midpoint of the scored guide as stated.
  - `unit` 'currency' | 'percent' | 'basis_points' | 'ratio' | 'shares' | 'count' | 'other', required: Unit of the stated guide.
  - `currency` string, nullable, required: ISO currency code when unit is currency.
  - `actual_value` number, nullable, required: Reported actual, scaled.
  - `actual_unit` string, nullable, required: Unit of the reported actual.
  - `comparability` 'comparable' | 'not_comparable', required: Whether the actual can be scored against the guide.
  - `vs_midpoint_delta` number, nullable, required: Actual minus guide midpoint, in the comparison unit.
  - `vs_midpoint_delta_pct` number, nullable, required: Actual vs midpoint as a percent of the midpoint; 5.0 means 5% above.
  - `vs_low_delta` number, nullable, required: Actual minus guide low bound.
  - `vs_high_delta` number, nullable, required: Actual minus guide high bound.
  - `guidance_source` Source, required: Full source information to be returned to end user.
    - `source_timestamp` string, date-time, required: Timestamp of the source item.
    - `source_table` 'news' | 'x_news' | 'youtube' | 'feeds' | 'x_posts' | 'tradingview_news' | 'telegram_messages' | 'web' | 'si_factor_assessments' | 'si_stakeholder_impacts' | 'fmp_company_descriptions' | 'fi_documents', required: Table (Type) of the source item.
    - `source_id` integer, required: 'id' of the source item
    - `url` string, required: Link to the source item. External sources link to the original page; first-party and synthesis sources link to their Ultralayer source page.
    - `source_metadata` union, required: Per-source metadata.
      - NewsSourceMetadata: source_metadata for rows where source_table == "news". News always has these two, so they are required (non-nullable). Do NOT widen this model for other sources; define a sibling model and register it in SOURCE_METADATA_BY_TABLE instead.
        - `title` string, required: Title of the news article.
        - `publisher` string, required: Publisher of the news article.
      - XNewsSourceMetadata: source_metadata for rows where source_table == "x_news". Only title: source_metadata is reserved for essential or genuinely filterable fields. x_id is encoded in Source.url; post_ids live in x_news.cluster_posts_results.
        - `title` string, required: X story title.
      - YouTubeSourceMetadata: source_metadata for rows where source_table == "youtube". Fields chosen for search filtering and source presentation: publisher links related channels; video_type distinguishes VIDEO, SHORT, and PODCAST; channel_name is the internal stable channel identity from YT_CONFIG. video_type / channel_name are optional because wire-derived citations only carry title/publisher from WireItemInternal. The documents-indexing path still sets both.
        - `title` string, required: YouTube video title.
        - `publisher` string, nullable, required: Internal publisher key linking related channels, e.g. bloomberg.
        - `video_type` string, nullable: VIDEO, SHORT, or PODCAST when known.
        - `channel_name` string, nullable: Internal stable channel identity from YT_CONFIG when known.
      - FeedsSourceMetadata: source_metadata for rows where source_table == "feeds". RSS headline rows. publisher is the internal feed/publisher key (nullable when unknown).
        - `title` string, required: Feed entry title.
        - `publisher` string, nullable, required: Internal publisher/feed key when known.
      - XPostsSourceMetadata: source_metadata for rows where source_table == "x_posts". Raw first-party posts have no title column — only publisher taxonomy.
        - `publisher` string, nullable, required: Publisher/rule-tag taxonomy when known.
      - TradingviewSourceMetadata: source_metadata for rows where source_table == "tradingview_news". TradingView stories always have a title; publisher is the normalized provider id.
        - `title` string, required: TradingView story title.
        - `publisher` string, nullable, required: Normalized provider id when known.
      - TelegramMessagesSourceMetadata: source_metadata for rows where source_table == "telegram_messages". Channel posts have no title column — only channel→publisher taxonomy.
        - `publisher` string, nullable, required: Channel→publisher taxonomy when known.
      - WebSourceMetadata: source_metadata for rows where source_table == "web".
        - `title` string, required: Title of the web record.
        - `record_type` string, required: Kind of web record (e.g. exa_search, azure_grounded).
      - SiFactorAssessmentSourceMetadata: source_metadata for rows where source_table == "si_factor_assessments". Lightweight identifiers only; full assessment content is retrieved via source_id. Assessments are first-party and have no public root URL; Source.coerce_source_metadata_and_url always mints /source/si_factor_assessments/{id}/{key} onto Source.url.
        - `factor_name` string, required: Factor name from the historical assessment.
        - `stakeholder_symbol` string, required: Stakeholder ticker from the historical assessment.
      - SiStakeholderImpactSourceMetadata: source_metadata for rows where source_table == "si_stakeholder_impacts". Lightweight identifiers only; full impact content (rationale, scores) is retrieved via source_id. Impacts are first-party and have no public root URL; Source.coerce_source_metadata_and_url always mints /source/si_stakeholder_impacts/{id}/{key} onto Source.url.
        - `stakeholder_symbol` string, required: Stakeholder ticker from the historical impact.
        - `stakeholder_name` string, required: Stakeholder name from the historical impact.
      - FmpCompanySourceMetadata: source_metadata for FMP data about one company. Today: rows where source_table == "fmp_company_descriptions". Lightweight identifiers only; the cited content is retrieved via source_id. Source.coerce_source_metadata_and_url mints FMP's page for symbol onto Source.url (ultralayer_python.source_url.build_fmp_company_url) for any table registered with this model. Nothing is stored for it. Another FMP company table reuses it by registering in SOURCE_METADATA_BY_TABLE and widening Source.source_table.
        - `symbol` string, required: Listing ticker of the company.
        - `company_name` string, required: Company name.
      - FilingDocumentSourceMetadata: source_metadata for rows where source_table == "fi_documents". No title column on fi_documents — do not invent one. document_class is not here: it is already GuidanceValue.source_type. fiscal_year / fiscal_quarter are the document's completed report period, not the guided period on the series — a Q2 release guiding FY revenue has Q2 here and FY on the series. Filing: fi_filings (nullable on a guidance update or an annual quarter). Call: fi_earnings_calls (always both; Q4 is 4). url lives on Source, not here: filing exhibits keep the document url; transcripts have none and Source mints a capability URL (ultralayer_python.source_url).
        - `symbol` string, required: Listing symbol of the filer.
        - `fiscal_year` integer, nullable, required: Filer fiscal year of the completed period this document reports, when it reports one.
        - `fiscal_quarter` integer, nullable, required: Filer fiscal quarter of that completed period; null for a full-year report or a document that reports no completed period.
        - `document_type` string, required: Source-native document label, e.g. EX-99.1 or transcript.
  - `actual_source` Source, required: Full source information to be returned to end user.
    - `source_timestamp` string, date-time, required: Timestamp of the source item.
    - `source_table` 'news' | 'x_news' | 'youtube' | 'feeds' | 'x_posts' | 'tradingview_news' | 'telegram_messages' | 'web' | 'si_factor_assessments' | 'si_stakeholder_impacts' | 'fmp_company_descriptions' | 'fi_documents', required: Table (Type) of the source item.
    - `source_id` integer, required: 'id' of the source item
    - `url` string, required: Link to the source item. External sources link to the original page; first-party and synthesis sources link to their Ultralayer source page.
    - `source_metadata` union, required: Per-source metadata.
      - NewsSourceMetadata: source_metadata for rows where source_table == "news". News always has these two, so they are required (non-nullable). Do NOT widen this model for other sources; define a sibling model and register it in SOURCE_METADATA_BY_TABLE instead.
        - `title` string, required: Title of the news article.
        - `publisher` string, required: Publisher of the news article.
      - XNewsSourceMetadata: source_metadata for rows where source_table == "x_news". Only title: source_metadata is reserved for essential or genuinely filterable fields. x_id is encoded in Source.url; post_ids live in x_news.cluster_posts_results.
        - `title` string, required: X story title.
      - YouTubeSourceMetadata: source_metadata for rows where source_table == "youtube". Fields chosen for search filtering and source presentation: publisher links related channels; video_type distinguishes VIDEO, SHORT, and PODCAST; channel_name is the internal stable channel identity from YT_CONFIG. video_type / channel_name are optional because wire-derived citations only carry title/publisher from WireItemInternal. The documents-indexing path still sets both.
        - `title` string, required: YouTube video title.
        - `publisher` string, nullable, required: Internal publisher key linking related channels, e.g. bloomberg.
        - `video_type` string, nullable: VIDEO, SHORT, or PODCAST when known.
        - `channel_name` string, nullable: Internal stable channel identity from YT_CONFIG when known.
      - FeedsSourceMetadata: source_metadata for rows where source_table == "feeds". RSS headline rows. publisher is the internal feed/publisher key (nullable when unknown).
        - `title` string, required: Feed entry title.
        - `publisher` string, nullable, required: Internal publisher/feed key when known.
      - XPostsSourceMetadata: source_metadata for rows where source_table == "x_posts". Raw first-party posts have no title column — only publisher taxonomy.
        - `publisher` string, nullable, required: Publisher/rule-tag taxonomy when known.
      - TradingviewSourceMetadata: source_metadata for rows where source_table == "tradingview_news". TradingView stories always have a title; publisher is the normalized provider id.
        - `title` string, required: TradingView story title.
        - `publisher` string, nullable, required: Normalized provider id when known.
      - TelegramMessagesSourceMetadata: source_metadata for rows where source_table == "telegram_messages". Channel posts have no title column — only channel→publisher taxonomy.
        - `publisher` string, nullable, required: Channel→publisher taxonomy when known.
      - WebSourceMetadata: source_metadata for rows where source_table == "web".
        - `title` string, required: Title of the web record.
        - `record_type` string, required: Kind of web record (e.g. exa_search, azure_grounded).
      - SiFactorAssessmentSourceMetadata: source_metadata for rows where source_table == "si_factor_assessments". Lightweight identifiers only; full assessment content is retrieved via source_id. Assessments are first-party and have no public root URL; Source.coerce_source_metadata_and_url always mints /source/si_factor_assessments/{id}/{key} onto Source.url.
        - `factor_name` string, required: Factor name from the historical assessment.
        - `stakeholder_symbol` string, required: Stakeholder ticker from the historical assessment.
      - SiStakeholderImpactSourceMetadata: source_metadata for rows where source_table == "si_stakeholder_impacts". Lightweight identifiers only; full impact content (rationale, scores) is retrieved via source_id. Impacts are first-party and have no public root URL; Source.coerce_source_metadata_and_url always mints /source/si_stakeholder_impacts/{id}/{key} onto Source.url.
        - `stakeholder_symbol` string, required: Stakeholder ticker from the historical impact.
        - `stakeholder_name` string, required: Stakeholder name from the historical impact.
      - FmpCompanySourceMetadata: source_metadata for FMP data about one company. Today: rows where source_table == "fmp_company_descriptions". Lightweight identifiers only; the cited content is retrieved via source_id. Source.coerce_source_metadata_and_url mints FMP's page for symbol onto Source.url (ultralayer_python.source_url.build_fmp_company_url) for any table registered with this model. Nothing is stored for it. Another FMP company table reuses it by registering in SOURCE_METADATA_BY_TABLE and widening Source.source_table.
        - `symbol` string, required: Listing ticker of the company.
        - `company_name` string, required: Company name.
      - FilingDocumentSourceMetadata: source_metadata for rows where source_table == "fi_documents". No title column on fi_documents — do not invent one. document_class is not here: it is already GuidanceValue.source_type. fiscal_year / fiscal_quarter are the document's completed report period, not the guided period on the series — a Q2 release guiding FY revenue has Q2 here and FY on the series. Filing: fi_filings (nullable on a guidance update or an annual quarter). Call: fi_earnings_calls (always both; Q4 is 4). url lives on Source, not here: filing exhibits keep the document url; transcripts have none and Source mints a capability URL (ultralayer_python.source_url).
        - `symbol` string, required: Listing symbol of the filer.
        - `fiscal_year` integer, nullable, required: Filer fiscal year of the completed period this document reports, when it reports one.
        - `fiscal_quarter` integer, nullable, required: Filer fiscal quarter of that completed period; null for a full-year report or a document that reports no completed period.
        - `document_type` string, required: Source-native document label, e.g. EX-99.1 or transcript.

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/ultralayer/apis/ultralayer-api.md) · [All operations](https://skmtc.dev/ultralayer/apis/ultralayer-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ultralayer/apis/ultralayer-api/revisions/4185459222be?raw)