> ## 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.

# Events and calendars fields

> Definitions, types, allowed values, and defaults for events and calendars.

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/calendar/events`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `from` | query | string (date) | required | Inclusive start date of the requested range in YYYY-MM-DD format. |
| `to` | query | string (date) | required | Inclusive end date of the requested range in YYYY-MM-DD format. |
| `market` | query | string or null | optional | Market label used to filter the calendar selection. |
| `type` | query | array of string or null | optional | Filter by the endpoint's event or disclosure category. Repeat the parameter where an array is accepted. |
| `status` | query | array of string or null | optional | Filter by the resource's lifecycle status. Accepted values depend on the endpoint. |
| `scope` | query | string | optional | Statement reporting scope to select, such as consolidated or separate. Allowed values: `all`, `tracked`. Default: `"all"`. |
| `company_id` | query | string (uuid) or null | optional | Filter or identify a company using its stable Rangler identifier. |
| `sector` | query | string or null | optional | Filter by the company's stored sector label. |
| `q` | query | string or null | optional | Search text matched against the resource's name, ticker, or documented searchable fields. |
| `country_code` | query | string or null | optional | Filter by ISO 3166-1 alpha-2 market country code |

### `GET /v1/calendar/events/export`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `from` | query | string (date) | required | Inclusive start date of the requested range in YYYY-MM-DD format. |
| `to` | query | string (date) | required | Inclusive end date of the requested range in YYYY-MM-DD format. |
| `market` | query | string or null | optional | Market label used to filter the calendar selection. |
| `type` | query | array of string or null | optional | Filter by the endpoint's event or disclosure category. Repeat the parameter where an array is accepted. |
| `status` | query | array of string or null | optional | Filter by the resource's lifecycle status. Accepted values depend on the endpoint. |
| `scope` | query | string | optional | Statement reporting scope to select, such as consolidated or separate. Allowed values: `all`, `tracked`. Default: `"all"`. |
| `company_id` | query | string (uuid) or null | optional | Filter or identify a company using its stable Rangler identifier. |
| `sector` | query | string or null | optional | Filter by the company's stored sector label. |
| `q` | query | string or null | optional | Search text matched against the resource's name, ticker, or documented searchable fields. |
| `country_code` | query | string or null | optional | Filter by ISO 3166-1 alpha-2 market country code |

### `GET /v1/events`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `cursor` | query | string or null | optional | Seek cursor over the event freshness timestamp `coalesce(source_published_at, occurred_at, created_at)` plus event id. |
| `type` | query | array of string or null | optional | Filter by the endpoint's event or disclosure category. Repeat the parameter where an array is accepted. |
| `company_id` | query | array of string (uuid) or null | optional | Filter or identify a company using its stable Rangler identifier. |
| `fund_id` | query | array of string (uuid) or null | optional | Filter or identify a fund using its stable Rangler identifier. |
| `entity` | query | string or null | optional | Filter events by the affected entity using the endpoint's documented identifier format. |
| `from` | query | string (date-time) or null | optional | Inclusive lower bound on the event freshness timestamp `coalesce(source_published_at, occurred_at, created_at)`. |
| `to` | query | string (date-time) or null | optional | Inclusive upper bound on the event freshness timestamp `coalesce(source_published_at, occurred_at, created_at)`. |
| `limit` | query | integer | optional | Maximum number of records to return in this page; the schema gives the allowed range. Default: `25`. |

### `GET /v1/events/upcoming`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `symbol` | query | array of string or null | optional | Trading symbol used to filter the requested events or observations. |
| `company_name` | query | array of string or null | optional | Company name used to narrow the upcoming-event selection. |
| `from` | query | string or null | optional | Inclusive start date of the requested range in YYYY-MM-DD format. |
| `to` | query | string 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: `8`. |

### `GET /v1/companies/{company_id}/events`

| Parameter | Location | Type | Presence | Meaning |
| - | - | - | - | - |
| `company_id` | path | string (uuid) | required | Filter or identify a company using its stable Rangler identifier. |
| `cursor` | query | string or null | optional | Seek cursor over the event freshness timestamp `coalesce(source_published_at, occurred_at, created_at)` plus event id. |
| `type` | query | array of string or null | optional | Filter by the endpoint's event or disclosure category. Repeat the parameter where an array is accepted. |
| `from` | query | string (date-time) or null | optional | Inclusive lower bound on the event freshness timestamp `coalesce(source_published_at, occurred_at, created_at)`. |
| `to` | query | string (date-time) or null | optional | Inclusive upper bound on the event freshness timestamp `coalesce(source_published_at, occurred_at, created_at)`. |
| `limit` | query | integer | optional | Maximum number of records to return in this page; the schema gives the allowed range. Default: `25`. |

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

## Company calendar company

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `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. |
| `sector` | string or null | optional | Industry sector assigned to the company, when known. |
| `exchange` | string or null | optional | Exchange or trading venue code, such as NGX or NASD. |
| `market_cap_display` | string or null | optional | Formatted market-capitalization label for display; do not parse it for calculations. |

<a id="company-calendar-event-read" />

## Company calendar event

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `market` | string | required | Market associated with the company-calendar event. |
| `event_type` | string | required | Company event category; the field schema lists the supported categories. Allowed values: `financial_results`, `board_meeting`, `agm`, `egm`, `corporate_action`, `earnings_forecast`, `dividend_payment`. |
| `status` | string | required | Calendar lifecycle: scheduled is planned, revised has a changed schedule, reported has occurrence evidence, overdue has passed without such evidence, past is historical, and cancelled was withdrawn. Allowed values: `scheduled`, `revised`, `reported`, `overdue`, `past`, `cancelled`. |
| `title` | string | required | Human-readable title of the resource or source document. |
| `description` | string or null | optional | Human-readable explanation or source description of this resource. |
| `event_date` | string (date) | required | Date used to place the event on the calendar. |
| `scheduled_date` | string (date) or null | optional | Most recent scheduled calendar date of the event. |
| `scheduled_at` | string (date-time) or null | optional | Scheduled event timestamp when a specific time is known. |
| `actual_date` | string (date) or null | optional | Reported date the event occurred, when known. |
| `actual_at` | string (date-time) or null | optional | Reported occurrence timestamp when a specific time is known. |
| `initial_scheduled_date` | string (date) or null | optional | Original scheduled calendar date before a revision, when known. |
| `revised_scheduled_date` | string (date) or null | optional | Revised scheduled date announced after the original schedule, when known. |
| `date_precision` | string | required | Date precision: date for day-only evidence or datetime when a specific time is available. Allowed values: `date`, `datetime`. |
| `timezone` | string | required | IANA timezone associated with the scheduled event. |
| `fiscal_year` | integer or null | optional | Issuer fiscal year covered by the value; it can differ from the calendar year. |
| `fiscal_period` | string or null | optional | Fiscal-period label associated with the event, when known. |
| `period_end` | string (date) or null | optional | Inclusive ending date of the reporting or selection window. |
| `company` | [Company calendar company](/fields/events#company-calendar-company-read) | required | Company identity or details associated with this record. |
| `sources` | array of [Company calendar source](/fields/events#company-calendar-source-read) | required | Evidence or source references supporting the returned information. |
| `reported_filing_id` | string (uuid) or null | optional | Identifier of the filing supplying reported-event evidence. |

<a id="company-calendar-page" />

## Company calendar page

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Company calendar event](/fields/events#company-calendar-event-read) | required | Returned records or observations. The item schema defines each element's fields. |
| `summary` | [Company calendar summary](/fields/events#company-calendar-summary-read) | required | Counts and busiest-day information for the returned calendar selection. |
| `updated_at` | string (date-time) or null | optional | Timestamp when Rangler last updated this record. |

<a id="company-calendar-source-read" />

## Company calendar source

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `kind` | string | required | Kind of entity or source represented by this object. |
| `label` | string | required | Human-readable label. Use the associated key or identifier for programmatic matching. |
| `external_id` | string | required | Source-provided event or record identifier. |
| `url` | string or null | optional | URL of the source document, article, or resource. |
| `title` | string or null | optional | Human-readable title of the resource or source document. |
| `published_at` | string (date-time) or null | optional | Publication timestamp of the source document or article when known. |
| `effective_date` | string (date) or null | optional | Date the disclosed change or corporate action takes effect. |
| `initial_scheduled_date` | string (date) or null | optional | Original scheduled calendar date before a revision, when known. |
| `revised_scheduled_date` | string (date) or null | optional | Revised scheduled date announced after the original schedule, when known. |
| `filing_id` | string (uuid) or null | optional | Stable Rangler identifier of the source filing. |
| `signal_id` | string (uuid) or null | optional | Identifier of the extracted filing signal supporting the event. |

<a id="company-calendar-summary-read" />

## Company calendar summary

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `total` | integer | required | Total number of events in the returned calendar summary. |
| `scheduled` | integer | required | Number of events classified as scheduled in the calendar summary. |
| `reported` | integer | required | Number of events with reported-occurrence evidence in the calendar summary. |
| `today` | integer | required | Number of summarized events falling on today's date. |
| `next_7_days` | integer | required | Number of summarized events falling within the next seven days. |
| `busiest_day` | string (date) or null | optional | Date with the greatest number of summarized events. |
| `busiest_day_count` | integer | required | Number of events on busiest\_day. |

<a id="event-read" />

## Event

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string (uuid) | required | Stable Rangler event identifier. Store it to avoid processing an event twice. |
| `type` | string | required | Stable Rangler event type in version v1. Public read APIs use `filing.new` for a filing disclosure and only include events created from automated analysis after Rangler's checks pass. Allowed values: `filing.new`, `filing.signal.created`, `financials.published`, `board_meeting.notice`, `board_change.detected`, `dividend.declared`, `rights.issue.announced`, `bonus.issue.announced`, `director_dealing.disclosed`, `company.meeting.scheduled`, `company.meeting.stream.scheduled`, `company.meeting.stream.live`, `company.meeting.stream.ended`, `company.meeting.stream.replay_available`, `fund.snapshot.updated`, `fund.disclosure.updated`. |
| `occurred_at` | string (date-time) | required | Ordering timestamp used for feed sorting and cursor progression. Semantics depend on event type. |
| `created_at` | string (date-time) | required | When Rangler created the event record. |
| `entity_kind` | string | required | Primary entity class attached to the event, such as filing or fund. |
| `entity_id` | string (uuid) | required | Identifier of the primary entity attached to the event. |
| `company_id` | string (uuid) or null | optional | Issuer identifier when the event is company-scoped. |
| `fund_id` | string (uuid) or null | optional | Fund identifier when the event is fund-scoped. |
| `source_kind` | string | required | Type of source Rangler used, such as filing or sandbox\_event. |
| `source_id` | string (uuid) | required | Rangler identifier for the source record. |
| `title` | string | required | Short event title intended for operators and product surfaces. |
| `summary` | string | required | Short event summary. |
| `severity` | string | required | Rangler severity label for the event. |
| `source_url` | string or null | optional | Direct source document or source page URL when known. |
| `source_published_at` | string (date-time) or null | optional | When the upstream filing, factsheet, or source page was published, if known. |
| `data` | object | required | Event-specific payload for Rangler API v1. Contains the typed filing, signal, fund, or snapshot fields documented per event type. `filing.new` may include `data.signal` when Rangler has a usable filing summary. Raw lifecycle event rows are exposed only through raw event endpoints. |

<a id="events-page" />

## Events page

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Event](/fields/events#event-read) | required | Returned records or observations. The item schema defines each element's fields. |
| `next_cursor` | string or null | optional | Opaque cursor for the next page. Pass it unchanged as cursor; null means no next page. |

<a id="upcoming-event-read" />

## Upcoming event

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `id` | string | required | Stable Rangler identifier for this record. Use the value exactly as returned. |
| `source_id` | integer or string (uuid) or string or null | optional | Identifier of the source record; interpret it together with source\_kind. |
| `source_kind` | string | optional | Category of the source record used as evidence. Allowed values: `ngx_release_calendar`, `filing_signal`, `company_meeting_intent`, `filing`, `dividend_lifecycle`. Default: `"ngx_release_calendar"`. |
| `filing_id` | string (uuid) or null | optional | Stable Rangler identifier of the source filing. |
| `title` | string | required | Human-readable title of the resource or source document. |
| `company_name` | string | required | Display name of the company. |
| `company_symbol` | string or null | optional | Trading symbol of the company associated with the event. |
| `company_isin` | string or null | optional | ISIN of the company security associated with the event. |
| `scheduled_date` | string | required | Most recent scheduled calendar date of the event. |
| `initial_scheduled_date` | string or null | optional | Original scheduled calendar date before a revision, when known. |
| `revised_scheduled_date` | string or null | optional | Revised scheduled date announced after the original schedule, when known. |
| `is_date_revised` | boolean | required | Whether the stored event date was revised from an earlier announcement. |
| `comments` | string or null | optional | Current explanatory comments attached to the event. |
| `proposed_comments` | string or null | optional | Comments describing the originally proposed event. |
| `actual_comments` | string or null | optional | Comments describing the reported occurrence or outcome. |
| `meeting_time` | string or null | optional | Meeting time as disclosed; do not infer a timezone without accompanying evidence. |
| `venue` | string or null | optional | Disclosed physical venue or meeting location. |
| `meeting_format` | string or null | optional | Disclosed meeting format, such as physical, virtual, or hybrid. |
| `confidence` | number or null | optional | Confidence score between 0 and 1. It is not a guarantee of correctness. |
| `source_url` | string | required | URL of the evidence supporting this record. |

<a id="upcoming-events-page" />

## Upcoming events page

| Field | Type | Presence | Meaning |
| - | - | - | - |
| `data` | array of [Upcoming event](/fields/events#upcoming-event-read) | required | Returned records or observations. The item schema defines each element's fields. |


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