> For the complete documentation index, see [llms.txt](https://docs.gridstatus.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.gridstatus.io/developers/concepts/breaking-changes.md). # Breaking Changes Occasionally, we make changes that are not backward compatible and require customers to update existing queries or integrations. This page describes what constitutes a breaking change, how we communicate those changes, and what you should do when one affects you. ## Why breaking changes happen We avoid breaking changes whenever possible. When one is necessary, we carefully weigh the benefits of making the change against the disruption to existing integrations. Common reasons include: * **Adapting to changes from the source** when the source significantly changes or discontinues a dataset, field, or reporting methodology. * **Correcting implementation errors** where our data or data model did not match the upstream source. * **Improving our data model** when we determine there is a more accurate or consistent way to represent the data. ## What is a breaking change? A breaking change is any change that is not backward compatible with existing queries or integrations. Backward-compatible changes, such as adding new columns, are not considered breaking changes. We treat the following as breaking changes: * **Removing a column** from a dataset. * **Renaming a column** from a dataset. * **Changing a dataset's ID.** * **Changing dataset metadata** in a way that changes query results, such as its primary key, time index column, publish time column, or subseries index. * **Deprecating a dataset**, meaning we announce a future date on which it will be removed or stop updating. * **Retiring a dataset**, meaning it stops receiving new data even though historical data remains queryable. Some changes are not considered breaking and may ship without advance notice. These include: * **Adding a new column** * **Backfilling additional historical data** * **Correcting data errors** so values match the upstream source. ## How we notify you We target notifications to customers who use the affected dataset rather than sending every update to every customer. This helps ensure important breaking change notices receive attention instead of getting lost among irrelevant alerts. * **Who we notify:** Any customer who has queried an affected dataset through our API or Snowflake marketplace in the last 30 days. * **How we reach you:** By email, sent to the address associated with the API key used to make those queries. Please keep this address monitored. * **What the notice contains:** * The affected dataset and the specific change. * The date the change takes effect. * The reason for the change. * How to update your integration, including a migration path when one is available. * **Timing:** We aim to give advance notice before a breaking change takes effect when possible. * In cases where the upstream source has changed the data we may have to make breaking changes immediately to avoid data loss. * When we are able to give advance notice, we will do so at least 10 business days in advance. ## How to respond to a breaking change 1. **Read the notice in full** and identify which datasets, columns, or dataset IDs you depend on. 2. **Follow the migration steps** in the notice to update your queries, column references, or pipeline configuration. 3. **Test against the new behavior** before the effective date. Where possible we give you a way to validate the new schema ahead of time. 4. **Get in touch** if the change affects you in a way the notice does not cover, or if you need more time. ## Questions If you have questions about this policy or a specific change, contact us at . --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.gridstatus.io/developers/concepts/breaking-changes.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.