> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rangler.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Forecasts and analyst views fields

> Definitions, types, allowed values, and defaults for forecasts and analyst views.

Use this reference with the endpoint documentation. A required field must be present; a nullable field can still contain `null`. Missing data does not mean zero. See [Field guide](/field-guide) for unit and status conventions.

### `GET /v1/estimates/contributors/{contributor_kind}/{contributor_key}`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `contributor_kind` | path | string | required | Category of forecast contributor to select. |
| `contributor_key` | path | string | required | Stable key of the forecast contributor to select. |

### `GET /v1/estimates/companies`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `q` | query | string or null | optional | Search text matched against the resource's name, ticker, or documented searchable fields. |
| `include_uncovered` | query | boolean | optional | Include companies with no forecast coverage when true. Default: `false`. |
| `limit` | query | integer | optional | Maximum number of records to return in this page; the schema gives the allowed range. Default: `100`. |

### `GET /v1/companies/{company_id}/estimates/metrics`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |

### `GET /v1/companies/{company_id}/estimates/sources/{estimate_id}/geometry`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |
| `estimate_id` | path | string (uuid) | required | Identifier of the forecast whose source evidence is requested. |

### `GET /v1/companies/{company_id}/estimates/grid`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |
| `display_currency` | query | string or null | optional | Currency requested for displaying eligible monetary values. |

### `GET /v1/companies/{company_id}/estimates/{metric_key}`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |
| `metric_key` | path | string | required | Forecast metric key to select. |
| `display_currency` | query | string or null | optional | Currency requested for displaying eligible monetary values. |

### `GET /v1/companies/{company_id}/estimates/{metric_key}/revision-trends`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |
| `metric_key` | path | string | required | Forecast metric key to select. |
| `display_currency` | query | string or null | optional | Currency requested for displaying eligible monetary values. |

### `GET /v1/companies/{company_id}/estimates/{metric_key}/revisions/{fiscal_year}`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |
| `metric_key` | path | string | required | Forecast metric key to select. |
| `fiscal_year` | path | integer | required | Issuer fiscal year to select. |

### `GET /v1/analyst-recommendations`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | query | string (uuid) or null | optional | Filter or identify a company using its stable Rangler identifier. |
| `ticker` | query | string or null | optional | Trading symbol used to filter the company or recommendation selection. |
| `provider` | query | string or null | optional | Filter by the stable fund-manager or research-provider key. |
| `from` | query | string (date) or null | optional | Inclusive start date of the requested range in YYYY-MM-DD format. |
| `to` | query | string (date) or null | optional | Inclusive end date of the requested range in YYYY-MM-DD format. |
| `limit` | query | integer | optional | Maximum number of records to return in this page; the schema gives the allowed range. Default: `100`. |

### `GET /v1/analyst-recommendations/weekly`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `as_of` | query | string (date) or null | optional | Date at which to evaluate the research selection; the endpoint schema specifies its default. |
| `period_start` | query | string (date) or null | optional | Inclusive starting date of the research reporting window. |
| `period_end` | query | string (date) or null | optional | Inclusive ending date of the research reporting window. |
| `sector` | query | string or null | optional | Filter by the company's stored sector label. |

### `GET /v1/companies/{company_id}/analyst-recommendations`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |
| `from` | query | string (date) or null | optional | Inclusive start date of the requested range in YYYY-MM-DD format. |
| `to` | query | string (date) or null | optional | Inclusive end date of the requested range in YYYY-MM-DD format. |
| `limit` | query | integer | optional | Maximum number of records to return in this page; the schema gives the allowed range. Default: `100`. |

### `GET /v1/companies/{company_id}/analyst-insight`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |
| `as_of` | query | string (date) or null | optional | Date at which to evaluate the research selection; the endpoint schema specifies its default. |
| `max_age_days` | query | integer | optional | Maximum age in days of recommendations included in the analyst view. Default: `100`. |
| `min_confidence` | query | number | optional | Minimum confidence score, between 0 and 1, for included recommendations. Default: `0.6`. |
| `change_lookback_days` | query | integer | optional | Number of days to look back for rating upgrades and downgrades. Default: `730`. |
| `change_limit` | query | integer | optional | Maximum number of rating changes to return. Default: `20`. |

<a id="analyst-price-target-summary-read" />

## Analyst price target summary

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `currency` | string or null | optional | Currency of the associated monetary value, normally an ISO 4217 code such as NGN. |
| `target_count` | integer | required | Number of comparable price targets included in the summary. |
| `low` | number or null | optional | Lowest comparable forecast or target value in the displayed unit and currency. |
| `mean` | number or null | optional | Arithmetic mean of comparable values in the displayed unit and currency. |
| `median` | number or null | optional | Median of comparable values in the displayed unit and currency. |
| `high` | number or null | optional | Highest comparable forecast or target value in the displayed unit and currency. |
| `last_updated_at` | string (date-time) or null | optional | Timestamp of the latest observation contributing to the target summary. |
| `current_price` | number or null | optional | Stored market price used to calculate implied target upside. |
| `current_price_currency` | string or null | optional | Currency of current\_price. |
| `current_price_as_of` | string (date-time) or null | optional | Timestamp of the market price used for implied upside. |
| `implied_upside_low_pct` | number or null | optional | Implied upside to the lowest target: (target / current\_price - 1) \* 100, in percentage points. |
| `implied_upside_mean_pct` | number or null | optional | Implied upside to the mean target: (target / current\_price - 1) \* 100, in percentage points. |
| `implied_upside_median_pct` | number or null | optional | Implied upside to the median target: (target / current\_price - 1) \* 100, in percentage points. |
| `implied_upside_high_pct` | number or null | optional | Implied upside to the highest target: (target / current\_price - 1) \* 100, in percentage points. |
| `currency_mismatch_count` | integer | optional | Number of targets excluded because their currency differs from the selected target currency. Default: `0`. |
| `unknown_currency_count` | integer | optional | Number of targets excluded because their currency is unknown. Default: `0`. |
| `excluded_outlier_count` | integer | optional | Number of targets excluded by the target-summary outlier rule. Default: `0`. |

<a id="analyst-rating-distribution-read" />

## Analyst rating distribution

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `buy_count` | integer | required | Number of providers assigned to the buy rating bucket. |
| `hold_count` | integer | required | Number of providers assigned to the hold rating bucket. |
| `sell_count` | integer | required | Number of providers assigned to the sell rating bucket. |
| `unrated_count` | integer | required | Number of providers whose recommendations have no normalized rating. |
| `rated_count` | integer | required | Number of providers in the buy, hold, or sell buckets; excludes unrated providers. |
| `provider_count` | integer | required | Number of research providers represented in this selection. |
| `buy_pct` | number or null | optional | Buy providers as a percentage of rated\_count: 25 means 25%; null when rated\_count is zero. |
| `hold_pct` | number or null | optional | Hold providers as a percentage of rated\_count: 25 means 25%; null when rated\_count is zero. |
| `sell_pct` | number or null | optional | Sell providers as a percentage of rated\_count: 25 means 25%; null when rated\_count is zero. |
| `action_counts` | map of integer | required | Counts keyed by normalized recommendation label. |

<a id="analyst-recommendation-change-read" />

## Analyst recommendation change

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `provider_key` | string | required | Stable research-provider key. |
| `provider_display_name` | string | required | Human-readable research-provider name. |
| `direction` | string | required | Direction of the rating change: upgrade or downgrade. Allowed values: `upgrade`, `downgrade`. |
| `previous_recommendation_id` | string (uuid) | required | Identifier of the preceding recommendation. |
| `previous_recommendation` | string | required | Normalized label of the preceding recommendation. |
| `recommendation_id` | string (uuid) | required | Identifier of the new recommendation. |
| `recommendation` | string | required | Normalized recommendation label. Retain raw\_recommendation when showing the provider's wording. |
| `previous_target_price` | number or null | optional | Target price in the preceding recommendation, in currency. |
| `target_price` | number or null | optional | Analyst's target price per security unit in currency. |
| `currency` | string or null | optional | Currency of the associated monetary value, normally an ISO 4217 code such as NGN. |
| `changed_at` | string (date-time) | required | Timestamp of the recommendation change. |

<a id="analyst-recommendation-consensus-read" />

## Analyst recommendation consensus

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `ticker` | string | required | Exchange trading symbol when available. A ticker is not a substitute for the stable company ID. |
| `company_id` | string (uuid) or null | optional | Stable Rangler company identifier. |
| `company_name` | string or null | optional | Display name of the company. |
| `sector` | string or null | optional | Industry sector assigned to the company, when known. |
| `period_start` | string (date) | required | Inclusive starting date of the reporting or selection window. |
| `period_end` | string (date) | required | Inclusive ending date of the reporting or selection window. |
| `provider_count` | integer | required | Number of research providers represented in this selection. |
| `actionable_count` | integer | required | Number of recommendations with an actionable rating. |
| `action_counts` | map of integer | required | Counts keyed by normalized recommendation label. |
| `consensus_score` | number or null | optional | Average of the latest eligible firm scores on the 1-5 consensus scale. |
| `consensus_recommendation` | string or null | optional | Backend-derived strong\_buy, buy, hold, sell, or strong\_sell consensus label. |
| `recommendations` | array of [Analyst recommendation](/fields/research#analyst-recommendation-read) | required | Research-provider recommendations and their source evidence. |

<a id="analyst-recommendation-read" />

## Analyst recommendation

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `provider_key` | string | required | Stable research-provider key. |
| `provider_display_name` | string | required | Human-readable research-provider name. |
| `ticker` | string | required | Exchange trading symbol when available. A ticker is not a substitute for the stable company ID. |
| `raw_recommendation` | string | required | Recommendation wording as printed by the research provider. |
| `recommendation` | string | required | Normalized recommendation label. Retain raw\_recommendation when showing the provider's wording. |
| `period_start` | string (date) | required | Inclusive starting date of the reporting or selection window. |
| `period_end` | string (date) | required | Inclusive ending date of the reporting or selection window. |
| `research_report_id` | string (uuid) | required | Stable Rangler identifier of the source research report. |
| `company_id` | string (uuid) or null | optional | Stable Rangler company identifier. |
| `sector` | string or null | optional | Industry sector assigned to the company, when known. |
| `company_name` | string or null | optional | Display name of the company. |
| `target_price` | number or null | optional | Analyst's target price per security unit in currency. |
| `currency` | string or null | optional | Currency of the associated monetary value, normally an ISO 4217 code such as NGN. |
| `upside_pct` | number or null | optional | Source-reported potential upside in percentage points: 25 means 25%. |
| `sentiment_score` | integer or null | optional | Normalized rating score: bullish=5, neutral=3, bearish=1; unrated calls are null. |
| `is_actionable` | boolean | required | Whether the normalized recommendation expresses an actionable rating. |
| `source_title` | string or null | optional | Title of the evidence supporting this record. |
| `source_url` | string or null | optional | URL of the evidence supporting this record. |
| `source_excerpt` | string or null | optional | Text excerpt supporting the extracted value or event. |
| `confidence` | number or null | optional | Confidence score between 0 and 1. It is not a guarantee of correctness. |
| `published_at` | string (date-time) or null | optional | Publication timestamp of the source document or article when known. |

<a id="analyst-recommendation-weekly-page" />

## Analyst recommendation weekly page

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `period_start` | string (date) | required | Inclusive starting date of the reporting or selection window. |
| `period_end` | string (date) | required | Inclusive ending date of the reporting or selection window. |
| `data` | array of [Analyst recommendation consensus](/fields/research#analyst-recommendation-consensus-read) | required | Returned records or observations. The item schema defines each element's fields. |
| `total_count` | integer | required | Total number of matching records, which can exceed the returned page length. |

<a id="analyst-recommendations-page" />

## Analyst recommendations page

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Analyst recommendation](/fields/research#analyst-recommendation-read) | required | Returned records or observations. The item schema defines each element's fields. |
| `total_count` | integer | required | Total number of matching records, which can exceed the returned page length. |

<a id="company-analyst-insight-read" />

## Company analyst insight

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `company_id` | string (uuid) | required | Stable Rangler company identifier. |
| `ticker` | string | required | Exchange trading symbol when available. A ticker is not a substitute for the stable company ID. |
| `as_of` | string (date) | required | Date or timestamp to which the observation applies; follow this field's declared format. |
| `max_age_days` | integer | required | Maximum age in days applied when selecting research observations. |
| `min_confidence` | number | required | Minimum confidence score applied when selecting recommendations. |
| `latest_period_end` | string (date) or null | optional | Latest reporting-period end represented in the selected research. |
| `latest_published_at` | string (date-time) or null | optional | Latest source-publication timestamp in the selected records. |
| `consensus_score` | number or null | optional | Average of the latest eligible firm scores on the 1-5 consensus scale. |
| `consensus_recommendation` | string or null | optional | Backend-derived strong\_buy, buy, hold, sell, or strong\_sell consensus label. |
| `ratings` | [Analyst rating distribution](/fields/research#analyst-rating-distribution-read) | required | Provider counts and percentage distribution across normalized rating buckets. |
| `price_targets` | [Analyst price target summary](/fields/research#analyst-price-target-summary-read) | required | Comparable target-price summary and implied upside to the current price. |
| `recommendations` | array of [Analyst recommendation](/fields/research#analyst-recommendation-read) | required | Research-provider recommendations and their source evidence. |
| `recent_rating_changes` | array of [Analyst recommendation change](/fields/research#analyst-recommendation-change-read) | required | Recent upgrades and downgrades within the selected research window. |

<a id="company-estimate-metrics-read" />

## Company estimate metrics

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `company_id` | string (uuid) | required | Stable Rangler company identifier. |
| `company_name` | string | required | Display name of the company. |
| `ticker` | string or null | optional | Exchange trading symbol when available. A ticker is not a substitute for the stable company ID. |
| `company_category` | string | required | Company category used to choose the applicable forecast metrics. |
| `default_metric` | string or null | optional | Metric key selected by default for this company category. |
| `featured_metrics` | array of [Metric summary](/fields/research#metric-summary-read) | optional | Priority forecast metric definitions for the company. Default: `[]`. |
| `metrics` | array of [Metric summary](/fields/research#metric-summary-read) | optional | Forecast metric definitions or rows available for this company; inspect the declared item schema. Default: `[]`. |

<a id="company-estimates-grid-read" />

## Company estimates grid

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `company_id` | string (uuid) | required | Stable Rangler company identifier. |
| `company_name` | string | required | Display name of the company. |
| `ticker` | string or null | optional | Exchange trading symbol when available. A ticker is not a substitute for the stable company ID. |
| `available_display_currencies` | array of string | optional | Currency codes supported for displaying these monetary values. Default: `[]`. |
| `display_currency` | string or null | optional | Currency selected for the monetary values returned to the caller. |
| `reported_currency` | string or null | optional | Currency used in the underlying disclosure before display conversion. |
| `columns` | array of [Grid column](/fields/research#grid-column-read) | optional | Available actual and estimate columns, identified by fiscal year and period end. Default: `[]`. |
| `metrics` | array of [Grid metric](/fields/research#grid-metric-read) | optional | Forecast metric definitions or rows available for this company; inspect the declared item schema. Default: `[]`. |

<a id="contributor-estimate-read" />

## Contributor estimate

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `estimate_id` | string (uuid) | required | Identifier of the individual forecast observation. |
| `contributor_key` | string | required | Stable key identifying the forecast contributor. |
| `contributor_display_name` | string | required | Human-readable name of the forecast contributor. |
| `contributor_kind` | string | required | Forecast origin: external\_research, contributed, or guidance. |
| `value` | number | required | Forecast value normalized into base units and the selected display currency. |
| `reported_value` | number | required | Forecast value in the disclosure's reported currency before display conversion. |
| `reported_currency` | string or null | optional | Currency used in the underlying disclosure before display conversion. |
| `as_of_date` | string (date) | required | Calendar date to which these observations or values apply. |
| `as_of_at` | string (date-time) | required | Timestamp at which the forecast or consensus observation applies. |
| `unit` | string | required | Measurement unit of the associated value. Monetary units use the accompanying currency. |
| `currency` | string or null | optional | Currency of the associated monetary value, normally an ISO 4217 code such as NGN. |
| `research_report_id` | string (uuid) or null | optional | Stable Rangler identifier of the source research report. |
| `source_page_number` | integer or null | optional | One-based page number in the source PDF. |
| `source_excerpt` | string or null | optional | Text excerpt supporting the extracted value or event. |
| `contributor_note` | string or null | optional | Contributor's explanatory note when supplied. |
| `withdrawn_at` | string (date-time) or null | optional | Timestamp when this forecast was withdrawn, if applicable. |
| `value_scale` | string or null | optional | Magnitude printed by the source, such as units, thousands, or millions. |
| `included_in_consensus` | boolean | optional | Whether this forecast is eligible for the displayed consensus. False can preserve evidence without including an unresolvable scale. Default: `true`. |
| `logo_url` | string or null | optional | URL of the resource's logo when available. |

<a id="contributor-profile-read" />

## Contributor profile

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `contributor_kind` | string | required | Forecast origin: external\_research, contributed, or guidance. |
| `contributor_key` | string | required | Stable key identifying the forecast contributor. |
| `display_name` | string | required | Human-readable name of the metric or contributor. |
| `image_url` | string or null | optional | Contributor profile image URL when available. |
| `coverage` | integer | required | Number of distinct company-and-metric combinations covered by this contributor. |
| `total_submissions` | integer | required | Number of forecasts recorded for this contributor. |
| `scored_estimates` | integer | required | Number of forecasts that could be compared with eligible reported actuals. |
| `median_error_rate` | number or null | optional | Median of abs(estimate - actual) / abs(actual) \* 100, in percentage points. Lower is better; zero actuals and unavailable error rates are excluded. |
| `accuracy_percentile` | number or null | optional | Accuracy percentile from 0 to 100 among contributors of the same kind with at least five error rates. Higher is better; null when this contributor has fewer than five usable error rates. |
| `history` | array of [Contributor year score](/fields/research#contributor-year-score-read) | optional | Contributor accuracy observations grouped by fiscal year. Default: `[]`. |

<a id="contributor-year-score-read" />

## Contributor year score

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `fiscal_year` | integer | required | Issuer fiscal year covered by the value; it can differ from the calendar year. |
| `observations` | integer | required | Number of eligible observations used for the year's accuracy score. |
| `median_error_rate` | number or null | optional | Median of abs(estimate - actual) / abs(actual) \* 100, in percentage points. Lower is better; zero actuals and unavailable error rates are excluded. |
| `actual_sources` | array of object | optional | Statement evidence supporting the actuals used to score forecasts. Default: `[]`. |

<a id="covered-companies-read" />

## Covered companies

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Covered company](/fields/research#covered-company-read) | optional | Returned records or observations. The item schema defines each element's fields. Default: `[]`. |

<a id="covered-company-read" />

## Covered company

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `company_id` | string (uuid) | required | Stable Rangler company identifier. |
| `name` | string | required | Display name of the identified resource. |
| `ticker` | string | required | Exchange trading symbol when available. A ticker is not a substitute for the stable company ID. |
| `logo_url` | string or null | optional | URL of the resource's logo when available. |
| `country_code` | string or null | optional | Two-letter ISO 3166-1 country code identifying the market, such as NG. |
| `metric_count` | integer | required | Number of forecast metrics available for this company. |
| `contributor_count` | integer | required | Number of comparable contributors included in this group. |
| `latest_as_of` | string (date) or null | optional | Most recent forecast observation date available for this company. |

<a id="estimate-aggregate-read" />

## Estimate aggregate

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `contributor_count` | integer | required | Number of comparable contributors included in this group. |
| `mean` | number or null | optional | Arithmetic mean of comparable values in the displayed unit and currency. |
| `median` | number or null | optional | Median of comparable values in the displayed unit and currency. |
| `high` | number or null | optional | Highest comparable forecast or target value in the displayed unit and currency. |
| `low` | number or null | optional | Lowest comparable forecast or target value in the displayed unit and currency. |
| `standard_deviation` | number or null | optional | Sample standard deviation of comparable forecasts; null when fewer than two values are available. |
| `estimates` | array of [Contributor estimate](/fields/research#contributor-estimate-read) | optional | Individual forecasts and their contributor/source evidence. Default: `[]`. |

<a id="estimate-source-geometry-read" />

## Estimate source geometry

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `research_report_id` | string (uuid) | required | Stable Rangler identifier of the source research report. |
| `page` | integer | required | One-based page number in the source PDF. |
| `coordinate_space` | string | required | Coordinate system for the source region; pdf\_points\_top\_left uses PDF points from the top left. Allowed values: `pdf_points_top_left`. |
| `page_width` | number | required | Width of the PDF page in PDF points. |
| `page_height` | number | required | Height of the PDF page in PDF points. |
| `x` | number | required | Horizontal position of the source region's left edge in PDF points. |
| `y` | number | required | Vertical position of the source region's top edge in PDF points. |
| `width` | number | required | Width of the source region in PDF points. |
| `height` | number | required | Height of the source region in PDF points. |

<a id="grid-column-read" />

## Grid column

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `fiscal_year` | integer | required | Issuer fiscal year covered by the value; it can differ from the calendar year. |
| `period_end_date` | string (date) | required | Closing date of the reporting period. |
| `kind` | string | required | Column category: actual for a reported result or estimate for a forecast. Allowed values: `actual`, `estimate`. |
| `label` | string | required | Human-readable label. Use the associated key or identifier for programmatic matching. |

<a id="grid-metric-read" />

## Grid metric

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `metric_key` | string | required | Stable key of the forecast metric. |
| `display_name` | string | required | Human-readable name of the metric or contributor. |
| `unit_class` | string or null | optional | Metric unit category, used to distinguish amounts, per-share values, ratios, and counts. |
| `statement_scope` | string or null | optional | Financial section to which the metric belongs, such as income\_statement or balance\_sheet. |
| `display_order` | integer | optional | Sort position for displaying the metric within its financial section. Default: `0`. |
| `favourable_direction` | string | optional | Direction associated with a favourable outcome: higher, lower, or neutral. Default: `"neutral"`. |
| `periods` | array of [Grid period](/fields/research#grid-period-read) | optional | Fiscal-period forecast observations or aggregates. Default: `[]`. |

<a id="grid-period-read" />

## Grid period

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `fiscal_year` | integer | required | Issuer fiscal year covered by the value; it can differ from the calendar year. |
| `period_end_date` | string (date) | required | Closing date of the reporting period. |
| `actual` | number or null | optional | Reported actual for the metric in the response's normalized unit and display currency. |
| `actual_source` | object or null | optional | Statement-cell or derivation evidence supporting the reported actual. |
| `surprise_pct` | number or null | optional | Difference from mean research consensus: (actual - mean) / abs(mean) \* 100. Values are percentage points; null when unavailable or the baseline is zero. |
| `variance_pct` | number or null | optional | Difference from median research consensus: (actual - median) / abs(median) \* 100. Values are percentage points; null when unavailable or the baseline is zero. |
| `outcome_status` | string or null | optional | Comparison outcome: favourable, unfavourable, or neutral according to the metric's favourable direction; null when no comparison is available. |
| `external_research` | [Estimate aggregate](/fields/research#estimate-aggregate-read) | required | Forecast aggregate from external research contributors. |
| `contributed` | [Estimate aggregate](/fields/research#estimate-aggregate-read) | required | Forecast aggregate from user contributions. |
| `guidance` | [Estimate aggregate](/fields/research#estimate-aggregate-read) | required | Forecast aggregate from issuer guidance. |

<a id="metric-estimates-read" />

## Metric estimates

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `metric_key` | string | required | Stable key of the forecast metric. |
| `display_name` | string | required | Human-readable name of the metric or contributor. |
| `unit_class` | string or null | optional | Metric unit category, used to distinguish amounts, per-share values, ratios, and counts. |
| `available_display_currencies` | array of string | optional | Currency codes supported for displaying these monetary values. Default: `[]`. |
| `display_currency` | string or null | optional | Currency selected for the monetary values returned to the caller. |
| `reported_currency` | string or null | optional | Currency used in the underlying disclosure before display conversion. |
| `favourable_direction` | string | optional | Direction associated with a favourable outcome: higher, lower, or neutral. Default: `"neutral"`. |
| `periods` | array of [Period estimates](/fields/research#period-estimates-read) | optional | Fiscal-period forecast observations or aggregates. Default: `[]`. |

<a id="metric-revision-trends-read" />

## Metric revision trends

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `metric_key` | string | required | Stable key of the forecast metric. |
| `series` | array of [Revision trend series](/fields/research#revision-trend-series-read) | optional | Consensus history grouped by fiscal year and contributor category. Default: `[]`. |

<a id="metric-revisions-read" />

## Metric revisions

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `metric_key` | string | required | Stable key of the forecast metric. |
| `fiscal_year` | integer | required | Issuer fiscal year covered by the value; it can differ from the calendar year. |
| `revisions` | array of [Contributor estimate](/fields/research#contributor-estimate-read) | optional | Earlier values or changes, with their dates and source references. Default: `[]`. |

<a id="metric-summary-read" />

## Metric summary

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `metric_key` | string | required | Stable key of the forecast metric. |
| `display_name` | string | required | Human-readable name of the metric or contributor. |
| `unit_class` | string or null | optional | Metric unit category, used to distinguish amounts, per-share values, ratios, and counts. |
| `statement_scope` | string or null | optional | Financial section to which the metric belongs, such as income\_statement or balance\_sheet. |
| `display_order` | integer | optional | Sort position for displaying the metric within its financial section. Default: `0`. |
| `featured_order` | integer or null | optional | Sort position among featured metrics; null means not featured. |
| `favourable_direction` | string | optional | Direction associated with a favourable outcome: higher, lower, or neutral. Default: `"neutral"`. |

<a id="period-estimates-read" />

## Period estimates

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `fiscal_year` | integer | required | Issuer fiscal year covered by the value; it can differ from the calendar year. |
| `period_end_date` | string (date) | required | Closing date of the reporting period. |
| `actual` | number or null | optional | Reported actual for the metric in the response's normalized unit and display currency. |
| `actual_source` | object or null | optional | Statement-cell or derivation evidence supporting the reported actual. |
| `actual_published_at` | string (date-time) or null | optional | Publication timestamp of the statement supplying the actual. |
| `surprise_pct` | number or null | optional | Difference from mean research consensus: (actual - mean) / abs(mean) \* 100. Values are percentage points; null when unavailable or the baseline is zero. |
| `variance_pct` | number or null | optional | Difference from median research consensus: (actual - median) / abs(median) \* 100. Values are percentage points; null when unavailable or the baseline is zero. |
| `outcome_status` | string or null | optional | Comparison outcome: favourable, unfavourable, or neutral according to the metric's favourable direction; null when no comparison is available. |
| `favourable_direction` | string | optional | Direction associated with a favourable outcome: higher, lower, or neutral. Default: `"neutral"`. |
| `external_research` | [Estimate aggregate](/fields/research#estimate-aggregate-read) | required | Forecast aggregate from external research contributors. |
| `contributed` | [Estimate aggregate](/fields/research#estimate-aggregate-read) | required | Forecast aggregate from user contributions. |
| `guidance` | [Estimate aggregate](/fields/research#estimate-aggregate-read) | required | Forecast aggregate from issuer guidance. |

<a id="revision-trend-point-read" />

## Revision trend point

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `as_of_at` | string (date-time) | required | Timestamp at which the forecast or consensus observation applies. |
| `contributor_count` | integer | required | Number of comparable contributors included in this group. |
| `mean` | number or null | optional | Arithmetic mean of comparable values in the displayed unit and currency. |
| `median` | number or null | optional | Median of comparable values in the displayed unit and currency. |
| `high` | number or null | optional | Highest comparable forecast or target value in the displayed unit and currency. |
| `low` | number or null | optional | Lowest comparable forecast or target value in the displayed unit and currency. |
| `source` | [Revision trend source](/fields/research#revision-trend-source-read) | required | Forecast revision or withdrawal that produced this trend observation. |

<a id="revision-trend-series-read" />

## Revision trend series

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `fiscal_year` | integer | required | Issuer fiscal year covered by the value; it can differ from the calendar year. |
| `contributor_kind` | string | required | Forecast origin: external\_research, contributed, or guidance. |
| `points` | array of [Revision trend point](/fields/research#revision-trend-point-read) | optional | Chronological observations in this revision-trend series. Default: `[]`. |

<a id="revision-trend-source-read" />

## Revision trend source

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `event_type` | string | required | Forecast-history event: revision or withdrawal. Allowed values: `revision`, `withdrawal`. |
| `estimate_id` | string (uuid) | required | Identifier of the individual forecast observation. |
| `contributor_key` | string | required | Stable key identifying the forecast contributor. |
| `contributor_display_name` | string | required | Human-readable name of the forecast contributor. |
| `contributor_kind` | string | required | Forecast origin: external\_research, contributed, or guidance. |
| `reported_value` | number | required | Forecast value in the disclosure's reported currency before display conversion. |
| `reported_currency` | string or null | optional | Currency used in the underlying disclosure before display conversion. |
| `unit` | string | required | Measurement unit of the associated value. Monetary units use the accompanying currency. |
| `value_scale` | string or null | optional | Magnitude printed by the source, such as units, thousands, or millions. |
| `research_report_id` | string (uuid) or null | optional | Stable Rangler identifier of the source research report. |
| `source_page_number` | integer or null | optional | One-based page number in the source PDF. |
| `source_excerpt` | string or null | optional | Text excerpt supporting the extracted value or event. |
| `contributor_note` | string or null | optional | Contributor's explanatory note when supplied. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.