# Query Data ## GET /datasets/{dataset\_id}/query > Query Dataset ```json {"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/datasets/{dataset_id}/query":{"get":{"tags":["Query Data"],"summary":"Query Dataset","operationId":"query_dataset_v1_datasets__dataset_id__query_get","parameters":[{"name":"dataset_id","in":"path","required":true,"schema":{"type":"string","title":"Dataset ID","description":"ID of the dataset to query"},"description":"ID of the dataset to query"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"order","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/OrderBy"},{"type":"null"}],"description":"The order to order results by","default":"asc","title":"Order"},"description":"The order to order results by"},{"name":"filter_column","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The column to filter results by","title":"Filter Column"},"description":"The column to filter results by"},{"name":"filter_value","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"description":"The value to filter results by","title":"Filter Value"},"description":"The value to filter results by"},{"name":"filter_operator","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FilterOperator"},{"type":"null"}],"default":"=","title":"Filter Operator"}},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The maximum number of rows to return across all pages","title":"Limit"},"description":"The maximum number of rows to return across all pages"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"The page number of results to return","default":1,"title":"Page"},"description":"The page number of results to return"},{"name":"page_size","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The maximum number of rows to return in a single page","title":"Page Size"},"description":"The maximum number of rows to return in a single page"},{"name":"columns","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string"},{"type":"null"}],"description":"Comma separated list of columns to return. Defaults to all columns.","title":"Columns"},"description":"Comma separated list of columns to return. Defaults to all columns."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"timezone","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The timezone to use when interpreting timezone naive timestamps, resampling to frequencies one day or more, and returning results. A value of `market`can be provided to return results in the timezone of the source ISO for the dataset. If `market` is specified and the dataset does not have a source ISO, the timezone will default to UTC for the query. When provided, columns in the `timezone` will be suffixed with `_local`.","default":"UTC","title":"Timezone"},"description":"The timezone to use when interpreting timezone naive timestamps, resampling to frequencies one day or more, and returning results. A value of `market`can be provided to return results in the timezone of the source ISO for the dataset. If `market` is specified and the dataset does not have a source ISO, the timezone will default to UTC for the query. When provided, columns in the `timezone` will be suffixed with `_local`."},{"name":"time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"The time to filter results. Cannot be used with start_time or end_time.\n\nPossible values:\n\n- 'latest': Fetches the most recently reported data point.\n\n- A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.\n\n","title":"Time"},"description":"The time to filter results. Cannot be used with start_time or end_time.\n\nPossible values:\n\n- 'latest': Fetches the most recently reported data point.\n\n- A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.\n\n"},{"name":"time_comparison","in":"query","required":false,"schema":{"anyOf":[{"enum":["=",">",">=","<","<="],"type":"string"},{"type":"null"}],"description":"The comparison operator to use when filtering by time.\n\nPossible values:\n\n- '=': Fetches the data at the exact time.\n\n- '>': Fetches the earliest data after the provided time.\n\n- '>=': Fetches the earliest data on or after the provided time.\n\n- '<': Fetches the latest data before the provided time.\n\n- '<=': Fetches the latest data on or before the provided time.\n\n","default":"=","title":"Time Comparison"},"description":"The comparison operator to use when filtering by time.\n\nPossible values:\n\n- '=': Fetches the data at the exact time.\n\n- '>': Fetches the earliest data after the provided time.\n\n- '>=': Fetches the earliest data on or after the provided time.\n\n- '<': Fetches the latest data before the provided time.\n\n- '<=': Fetches the latest data on or before the provided time.\n\n"},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"The start time to filter results using the dataset's time_index_column. Data on or after this time will be returned. Only applies to datasets with a time_index_column","title":"Start Time"},"description":"The start time to filter results using the dataset's time_index_column. Data on or after this time will be returned. Only applies to datasets with a time_index_column"},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"The end time to filter results using the dataset's time_index_column. Data before this time will be returned. Only applies to datasets with a time_index_column","title":"End Time"},"description":"The end time to filter results using the dataset's time_index_column. Data before this time will be returned. Only applies to datasets with a time_index_column"},{"name":"publish_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"Controls the filtering based on the dataset's publish time.\n\nCannot be combined with publish_time_start or publish_time_end.Note: a dataset must have a time index column to use 'latest' or 'latest_before:' options.\n\nPossible values:\n\n- 'latest_report': Returns records only from the most recently published report.\n\n- 'latest': For any given timestamp, fetches the most recently reported data point associated with it.\n\n- A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.\n\n- 'latest_before:': Return the most recent forecast for each operating time where publish_time <= operating_time + offset (e.g., 'latest_before:-6 hours').\n\n - 'latest_before': shorthand for 'latest_before:-0 hours'. Used to get the most recent forecast prior to each operating time. This is useful because some forecasts are published after the operating time they are forecasting for.\n\n- 'latest_before:@': Return the latest forecast published before the specified time on the offset day (e.g., 'latest_before:-1 day@10:00:00').\n\n - 'window':: Returns all forecasts for each operating time published between the specified offset from the operating time and the operating time. In other words, where operating_time + offset <= publish_time <= operating_time. (e.g., 'window:-6 hours').\n\n - 'window:@': Returns all forecasts for each operating time published between the specified time on the offset day from the operating time and the operating time (e.g., 'window:-1 day@10:00:00').\n\n- None: No filtering based on publish time.\n\n","title":"Publish Time"},"description":"Controls the filtering based on the dataset's publish time.\n\nCannot be combined with publish_time_start or publish_time_end.Note: a dataset must have a time index column to use 'latest' or 'latest_before:' options.\n\nPossible values:\n\n- 'latest_report': Returns records only from the most recently published report.\n\n- 'latest': For any given timestamp, fetches the most recently reported data point associated with it.\n\n- A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.\n\n- 'latest_before:': Return the most recent forecast for each operating time where publish_time <= operating_time + offset (e.g., 'latest_before:-6 hours').\n\n - 'latest_before': shorthand for 'latest_before:-0 hours'. Used to get the most recent forecast prior to each operating time. This is useful because some forecasts are published after the operating time they are forecasting for.\n\n- 'latest_before:@': Return the latest forecast published before the specified time on the offset day (e.g., 'latest_before:-1 day@10:00:00').\n\n - 'window':: Returns all forecasts for each operating time published between the specified offset from the operating time and the operating time. In other words, where operating_time + offset <= publish_time <= operating_time. (e.g., 'window:-6 hours').\n\n - 'window:@': Returns all forecasts for each operating time published between the specified time on the offset day from the operating time and the operating time (e.g., 'window:-1 day@10:00:00').\n\n- None: No filtering based on publish time.\n\n"},{"name":"publish_time_start","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"The start time to filter results using the dataset's publish_time_column. Data on or after this time will be returned up to the publish_time_end if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time.","title":"Publish Time Start"},"description":"The start time to filter results using the dataset's publish_time_column. Data on or after this time will be returned up to the publish_time_end if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time."},{"name":"publish_time_end","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"The end time to filter results using the dataset's publish_index_column. Data before this time will be returned down the publish_time_start if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time.","title":"Publish Time End"},"description":"The end time to filter results using the dataset's publish_index_column. Data before this time will be returned down the publish_time_start if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time."},{"name":"resample_frequency","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The frequency to resample the data to. Must be one of:\n\n- \"1 minute\"\n- \"5 minutes\"\n- \"10 minutes\"\n- \"15 minutes\"\n- \"1 hour\"\n- \"1 day\"\n- \"1 week\"\n- \"1 month\"\n- \"1 year\"\n\nWhen resampling_frequency is specified, start_time and end_time values must also be provided. The only exception to this is when querying datasets that have a publish time and the publish time is specified as a specific timestamp or 'latest_report'.\n\nAdditionally, the number of days of data that can be queried is limited based on the resample frequency. The maximum number of days of data that can be queried for each resample frequency is listed below. There is no limit on days for resample frequencies not listed below.\n\n- 1 minute: 31 days\n- 5 minutes: 100 days\n- 10 minutes: 120 days\n- 15 minutes: 180 days\n- 1 hour: 365 days\n- 1 day: 1825 days","title":"Resample Frequency"},"description":"The frequency to resample the data to. Must be one of:\n\n- \"1 minute\"\n- \"5 minutes\"\n- \"10 minutes\"\n- \"15 minutes\"\n- \"1 hour\"\n- \"1 day\"\n- \"1 week\"\n- \"1 month\"\n- \"1 year\"\n\nWhen resampling_frequency is specified, start_time and end_time values must also be provided. The only exception to this is when querying datasets that have a publish time and the publish time is specified as a specific timestamp or 'latest_report'.\n\nAdditionally, the number of days of data that can be queried is limited based on the resample frequency. The maximum number of days of data that can be queried for each resample frequency is listed below. There is no limit on days for resample frequencies not listed below.\n\n- 1 minute: 31 days\n- 5 minutes: 100 days\n- 10 minutes: 120 days\n- 15 minutes: 180 days\n- 1 hour: 365 days\n- 1 day: 1825 days"},{"name":"resample_by","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string"},{"type":"null"}],"description":"A comma separated list of columns to group by before resampling. \n\n- When resampling, the data is always grouped by the time index column of the dataset.\n\n- If a value is provided for resample_by, the data will be grouped by the provided columns in addition to the time index column.\n\n- If the dataset has a subseries index and no value is provided for resample_by, the data will also be grouped by the subseries index column.\n\n- If the dataset has a publish time column and the publish_time parameter is not 'latest', the data will also be grouped by the publish time column.","title":"Resample By"},"description":"A comma separated list of columns to group by before resampling. \n\n- When resampling, the data is always grouped by the time index column of the dataset.\n\n- If a value is provided for resample_by, the data will be grouped by the provided columns in addition to the time index column.\n\n- If the dataset has a subseries index and no value is provided for resample_by, the data will also be grouped by the subseries index column.\n\n- If the dataset has a publish time column and the publish_time parameter is not 'latest', the data will also be grouped by the publish time column."},{"name":"resample_function","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ResampleFunction"},{"type":"null"}],"description":"The function to use when resampling. Defaults to \"mean\". Possible values are \"mean\", \"sum\", \"min\", \"max\", \"stddev\", \"count\". If resample is None, this is ignored.","default":"mean","title":"Resample Function"},"description":"The function to use when resampling. Defaults to \"mean\". Possible values are \"mean\", \"sum\", \"min\", \"max\", \"stddev\", \"count\". If resample is None, this is ignored."},{"name":"return_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ReturnFormat","description":"The return format of the response","default":"json"},"description":"The return format of the response"},{"name":"download","in":"query","required":false,"schema":{"type":"boolean","description":"Whether to download the file or not","default":false,"title":"Download"},"description":"Whether to download the file or not"},{"name":"json_schema","in":"query","required":false,"schema":{"$ref":"#/components/schemas/JSONSchema","description":"The json schema of the response","default":"array-of-objects"},"description":"The json schema of the response"},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/QueryDatasetResponse"},{"$ref":"#/components/schemas/CSVResponse"}],"title":"Response Query Dataset V1 Datasets Dataset Id Query Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"OrderBy":{"type":"string","enum":["asc","desc"],"title":"OrderBy"},"FilterOperator":{"type":"string","enum":["=","!=",">",">=","<","<=","in"],"title":"FilterOperator"},"ResampleFunction":{"type":"string","enum":["mean","sum","min","max","count","stddev","variance"],"title":"ResampleFunction"},"ReturnFormat":{"type":"string","enum":["json","csv"],"title":"ReturnFormat"},"JSONSchema":{"type":"string","enum":["array-of-objects","array-of-arrays"],"title":"JSONSchema"},"QueryDatasetResponse":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"data":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/MetadataResponse"},"dataset_metadata":{"$ref":"#/components/schemas/DatasetResponse"}},"type":"object","required":["status_code","data","meta","dataset_metadata"],"title":"QueryDatasetResponse"},"MetadataResponse":{"properties":{"page":{"type":"integer","title":"Page"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit"},"page_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Size"},"hasNextPage":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Hasnextpage"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},"type":"object","required":["page","limit","page_size","hasNextPage","cursor"],"title":"MetadataResponse"},"DatasetResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"earliest_available_time_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Earliest Available Time Utc"},"latest_available_time_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Latest Available Time Utc"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"last_checked_time_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checked Time Utc"},"primary_key_columns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Primary Key Columns"},"publish_time_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publish Time Column"},"time_index_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Time Index Column"},"subseries_index_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subseries Index Column"},"all_columns":{"anyOf":[{"items":{"$ref":"#/components/schemas/ColumnResponse"},"type":"array"},{"type":"null"}],"title":"All Columns"},"number_of_rows_approximate":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Number Of Rows Approximate"},"table_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Table Type"},"is_in_snowflake":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is In Snowflake"},"data_frequency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Frequency"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"publication_frequency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publication Frequency"},"is_published":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Published"},"created_at_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At Utc"},"status":{"anyOf":[{"$ref":"#/components/schemas/DatasetStatusEnum"},{"type":"null"}]},"popularity_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Popularity Rank"}},"type":"object","required":["id","name","description","earliest_available_time_utc","latest_available_time_utc","source","last_checked_time_utc","primary_key_columns","publish_time_column","time_index_column","subseries_index_column","all_columns","number_of_rows_approximate","table_type","is_in_snowflake","data_frequency","source_url","publication_frequency","is_published","created_at_utc","status"],"title":"DatasetResponse"},"ColumnResponse":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"is_numeric":{"type":"boolean","title":"Is Numeric"},"is_date":{"type":"boolean","title":"Is Date","default":false},"is_datetime":{"type":"boolean","title":"Is Datetime"}},"type":"object","required":["name","type","is_numeric","is_datetime"],"title":"ColumnResponse"},"DatasetStatusEnum":{"type":"string","enum":["retired","active","deprecated"],"title":"DatasetStatusEnum"},"CSVResponse":{"properties":{"file":{"anyOf":[{"$ref":"#/components/schemas/FileResponseData"},{"type":"null"}],"description":"The CSV data as a bytes object, a string, or a StreamingResponse object."},"content_type":{"type":"string","title":"Content Type","description":"The content type of the response.","default":"text/csv"}},"type":"object","title":"CSVResponse"},"FileResponseData":{"properties":{"media_type":{"type":"string","title":"Media Type"},"content":{"anyOf":[{"type":"string","format":"binary"},{"type":"string"}],"title":"Content"}},"type":"object","required":["media_type","content"],"title":"FileResponseData"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` ## Query Dataset by column value > Query a dataset by a column value\ > \ > This is a shortcut for \`/datasets/{dataset\_id}/query?filter\_column={filter\_column}\&filter\_value={filter\_value}\` ```json {"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/datasets/{dataset_id}/query/{filter_column_id}/{filter_value_path}":{"get":{"tags":["Query Data"],"summary":"Query Dataset by column value","description":"Query a dataset by a column value\n\nThis is a shortcut for `/datasets/{dataset_id}/query?filter_column={filter_column}&filter_value={filter_value}`","operationId":"query_dataset_column_value_v1_datasets__dataset_id__query__filter_column_id___filter_value_path__get","parameters":[{"name":"dataset_id","in":"path","required":true,"schema":{"type":"string","title":"Dataset Id"}},{"name":"filter_column_id","in":"path","required":true,"schema":{"type":"string","title":"Filter Column ID","description":"ID of the column to filter by"},"description":"ID of the column to filter by"},{"name":"filter_value_path","in":"path","required":true,"schema":{"type":"string","title":"Filter Value","description":"Value to filter by"},"description":"Value to filter by"},{"name":"api_key","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (query)","title":"Api Key"},"description":"API key for authentication (query)"},{"name":"return_format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/ReturnFormat","description":"The return format of the response","default":"json"},"description":"The return format of the response"},{"name":"download","in":"query","required":false,"schema":{"type":"boolean","description":"Whether to download the file or not","default":false,"title":"Download"},"description":"Whether to download the file or not"},{"name":"json_schema","in":"query","required":false,"schema":{"$ref":"#/components/schemas/JSONSchema","description":"The json schema of the response","default":"array-of-objects"},"description":"The json schema of the response"},{"name":"order","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/OrderBy"},{"type":"null"}],"description":"The order to order results by","default":"asc","title":"Order"},"description":"The order to order results by"},{"name":"filter_column","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The column to filter results by","title":"Filter Column"},"description":"The column to filter results by"},{"name":"filter_value","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"number"},{"type":"string"},{"type":"null"}],"description":"The value to filter results by","title":"Filter Value"},"description":"The value to filter results by"},{"name":"filter_operator","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/FilterOperator"},{"type":"null"}],"default":"=","title":"Filter Operator"}},{"name":"limit","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The maximum number of rows to return across all pages","title":"Limit"},"description":"The maximum number of rows to return across all pages"},{"name":"page","in":"query","required":false,"schema":{"type":"integer","description":"The page number of results to return","default":1,"title":"Page"},"description":"The page number of results to return"},{"name":"page_size","in":"query","required":false,"schema":{"anyOf":[{"type":"integer"},{"type":"null"}],"description":"The maximum number of rows to return in a single page","title":"Page Size"},"description":"The maximum number of rows to return in a single page"},{"name":"columns","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string"},{"type":"null"}],"description":"Comma separated list of columns to return. Defaults to all columns.","title":"Columns"},"description":"Comma separated list of columns to return. Defaults to all columns."},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},{"name":"timezone","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The timezone to use when interpreting timezone naive timestamps, resampling to frequencies one day or more, and returning results. A value of `market`can be provided to return results in the timezone of the source ISO for the dataset. If `market` is specified and the dataset does not have a source ISO, the timezone will default to UTC for the query. When provided, columns in the `timezone` will be suffixed with `_local`.","default":"UTC","title":"Timezone"},"description":"The timezone to use when interpreting timezone naive timestamps, resampling to frequencies one day or more, and returning results. A value of `market`can be provided to return results in the timezone of the source ISO for the dataset. If `market` is specified and the dataset does not have a source ISO, the timezone will default to UTC for the query. When provided, columns in the `timezone` will be suffixed with `_local`."},{"name":"time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"The time to filter results. Cannot be used with start_time or end_time.\n\nPossible values:\n\n- 'latest': Fetches the most recently reported data point.\n\n- A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.\n\n","title":"Time"},"description":"The time to filter results. Cannot be used with start_time or end_time.\n\nPossible values:\n\n- 'latest': Fetches the most recently reported data point.\n\n- A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.\n\n"},{"name":"time_comparison","in":"query","required":false,"schema":{"anyOf":[{"enum":["=",">",">=","<","<="],"type":"string"},{"type":"null"}],"description":"The comparison operator to use when filtering by time.\n\nPossible values:\n\n- '=': Fetches the data at the exact time.\n\n- '>': Fetches the earliest data after the provided time.\n\n- '>=': Fetches the earliest data on or after the provided time.\n\n- '<': Fetches the latest data before the provided time.\n\n- '<=': Fetches the latest data on or before the provided time.\n\n","default":"=","title":"Time Comparison"},"description":"The comparison operator to use when filtering by time.\n\nPossible values:\n\n- '=': Fetches the data at the exact time.\n\n- '>': Fetches the earliest data after the provided time.\n\n- '>=': Fetches the earliest data on or after the provided time.\n\n- '<': Fetches the latest data before the provided time.\n\n- '<=': Fetches the latest data on or before the provided time.\n\n"},{"name":"start_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"The start time to filter results using the dataset's time_index_column. Data on or after this time will be returned. Only applies to datasets with a time_index_column","title":"Start Time"},"description":"The start time to filter results using the dataset's time_index_column. Data on or after this time will be returned. Only applies to datasets with a time_index_column"},{"name":"end_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"The end time to filter results using the dataset's time_index_column. Data before this time will be returned. Only applies to datasets with a time_index_column","title":"End Time"},"description":"The end time to filter results using the dataset's time_index_column. Data before this time will be returned. Only applies to datasets with a time_index_column"},{"name":"publish_time","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"Controls the filtering based on the dataset's publish time.\n\nCannot be combined with publish_time_start or publish_time_end.Note: a dataset must have a time index column to use 'latest' or 'latest_before:' options.\n\nPossible values:\n\n- 'latest_report': Returns records only from the most recently published report.\n\n- 'latest': For any given timestamp, fetches the most recently reported data point associated with it.\n\n- A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.\n\n- 'latest_before:': Return the most recent forecast for each operating time where publish_time <= operating_time + offset (e.g., 'latest_before:-6 hours').\n\n - 'latest_before': shorthand for 'latest_before:-0 hours'. Used to get the most recent forecast prior to each operating time. This is useful because some forecasts are published after the operating time they are forecasting for.\n\n- 'latest_before:@': Return the latest forecast published before the specified time on the offset day (e.g., 'latest_before:-1 day@10:00:00').\n\n - 'window':: Returns all forecasts for each operating time published between the specified offset from the operating time and the operating time. In other words, where operating_time + offset <= publish_time <= operating_time. (e.g., 'window:-6 hours').\n\n - 'window:@': Returns all forecasts for each operating time published between the specified time on the offset day from the operating time and the operating time (e.g., 'window:-1 day@10:00:00').\n\n- None: No filtering based on publish time.\n\n","title":"Publish Time"},"description":"Controls the filtering based on the dataset's publish time.\n\nCannot be combined with publish_time_start or publish_time_end.Note: a dataset must have a time index column to use 'latest' or 'latest_before:' options.\n\nPossible values:\n\n- 'latest_report': Returns records only from the most recently published report.\n\n- 'latest': For any given timestamp, fetches the most recently reported data point associated with it.\n\n- A specific timestamp string (ISO 8601 format): Returns records that were published at the provided timestamp.\n\n- 'latest_before:': Return the most recent forecast for each operating time where publish_time <= operating_time + offset (e.g., 'latest_before:-6 hours').\n\n - 'latest_before': shorthand for 'latest_before:-0 hours'. Used to get the most recent forecast prior to each operating time. This is useful because some forecasts are published after the operating time they are forecasting for.\n\n- 'latest_before:@': Return the latest forecast published before the specified time on the offset day (e.g., 'latest_before:-1 day@10:00:00').\n\n - 'window':: Returns all forecasts for each operating time published between the specified offset from the operating time and the operating time. In other words, where operating_time + offset <= publish_time <= operating_time. (e.g., 'window:-6 hours').\n\n - 'window:@': Returns all forecasts for each operating time published between the specified time on the offset day from the operating time and the operating time (e.g., 'window:-1 day@10:00:00').\n\n- None: No filtering based on publish time.\n\n"},{"name":"publish_time_start","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"The start time to filter results using the dataset's publish_time_column. Data on or after this time will be returned up to the publish_time_end if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time.","title":"Publish Time Start"},"description":"The start time to filter results using the dataset's publish_time_column. Data on or after this time will be returned up to the publish_time_end if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time."},{"name":"publish_time_end","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"string","format":"date-time"},{"type":"null"}],"description":"The end time to filter results using the dataset's publish_index_column. Data before this time will be returned down the publish_time_start if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time.","title":"Publish Time End"},"description":"The end time to filter results using the dataset's publish_index_column. Data before this time will be returned down the publish_time_start if provided. Only applies to datasets with a publish_time_column. Cannot be used with publish_time."},{"name":"resample_frequency","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The frequency to resample the data to. Must be one of:\n\n- \"1 minute\"\n- \"5 minutes\"\n- \"10 minutes\"\n- \"15 minutes\"\n- \"1 hour\"\n- \"1 day\"\n- \"1 week\"\n- \"1 month\"\n- \"1 year\"\n\nWhen resampling_frequency is specified, start_time and end_time values must also be provided. The only exception to this is when querying datasets that have a publish time and the publish time is specified as a specific timestamp or 'latest_report'.\n\nAdditionally, the number of days of data that can be queried is limited based on the resample frequency. The maximum number of days of data that can be queried for each resample frequency is listed below. There is no limit on days for resample frequencies not listed below.\n\n- 1 minute: 31 days\n- 5 minutes: 100 days\n- 10 minutes: 120 days\n- 15 minutes: 180 days\n- 1 hour: 365 days\n- 1 day: 1825 days","title":"Resample Frequency"},"description":"The frequency to resample the data to. Must be one of:\n\n- \"1 minute\"\n- \"5 minutes\"\n- \"10 minutes\"\n- \"15 minutes\"\n- \"1 hour\"\n- \"1 day\"\n- \"1 week\"\n- \"1 month\"\n- \"1 year\"\n\nWhen resampling_frequency is specified, start_time and end_time values must also be provided. The only exception to this is when querying datasets that have a publish time and the publish time is specified as a specific timestamp or 'latest_report'.\n\nAdditionally, the number of days of data that can be queried is limited based on the resample frequency. The maximum number of days of data that can be queried for each resample frequency is listed below. There is no limit on days for resample frequencies not listed below.\n\n- 1 minute: 31 days\n- 5 minutes: 100 days\n- 10 minutes: 120 days\n- 15 minutes: 180 days\n- 1 hour: 365 days\n- 1 day: 1825 days"},{"name":"resample_by","in":"query","required":false,"schema":{"anyOf":[{"type":"array","items":{"type":"string"}},{"type":"string"},{"type":"null"}],"description":"A comma separated list of columns to group by before resampling. \n\n- When resampling, the data is always grouped by the time index column of the dataset.\n\n- If a value is provided for resample_by, the data will be grouped by the provided columns in addition to the time index column.\n\n- If the dataset has a subseries index and no value is provided for resample_by, the data will also be grouped by the subseries index column.\n\n- If the dataset has a publish time column and the publish_time parameter is not 'latest', the data will also be grouped by the publish time column.","title":"Resample By"},"description":"A comma separated list of columns to group by before resampling. \n\n- When resampling, the data is always grouped by the time index column of the dataset.\n\n- If a value is provided for resample_by, the data will be grouped by the provided columns in addition to the time index column.\n\n- If the dataset has a subseries index and no value is provided for resample_by, the data will also be grouped by the subseries index column.\n\n- If the dataset has a publish time column and the publish_time parameter is not 'latest', the data will also be grouped by the publish time column."},{"name":"resample_function","in":"query","required":false,"schema":{"anyOf":[{"$ref":"#/components/schemas/ResampleFunction"},{"type":"null"}],"description":"The function to use when resampling. Defaults to \"mean\". Possible values are \"mean\", \"sum\", \"min\", \"max\", \"stddev\", \"count\". If resample is None, this is ignored.","default":"mean","title":"Resample Function"},"description":"The function to use when resampling. Defaults to \"mean\". Possible values are \"mean\", \"sum\", \"min\", \"max\", \"stddev\", \"count\". If resample is None, this is ignored."},{"name":"x-api-key","in":"header","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"API key for authentication (header)","title":"X-Api-Key"},"description":"API key for authentication (header)"}],"responses":{"200":{"description":"Successful response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/QueryDatasetResponse"},{"$ref":"#/components/schemas/CSVResponse"}],"title":"Response Query Dataset Column Value V1 Datasets Dataset Id Query Filter Column Id Filter Value Path Get"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ReturnFormat":{"type":"string","enum":["json","csv"],"title":"ReturnFormat"},"JSONSchema":{"type":"string","enum":["array-of-objects","array-of-arrays"],"title":"JSONSchema"},"OrderBy":{"type":"string","enum":["asc","desc"],"title":"OrderBy"},"FilterOperator":{"type":"string","enum":["=","!=",">",">=","<","<=","in"],"title":"FilterOperator"},"ResampleFunction":{"type":"string","enum":["mean","sum","min","max","count","stddev","variance"],"title":"ResampleFunction"},"QueryDatasetResponse":{"properties":{"status_code":{"type":"integer","title":"Status Code"},"data":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Data"},"meta":{"$ref":"#/components/schemas/MetadataResponse"},"dataset_metadata":{"$ref":"#/components/schemas/DatasetResponse"}},"type":"object","required":["status_code","data","meta","dataset_metadata"],"title":"QueryDatasetResponse"},"MetadataResponse":{"properties":{"page":{"type":"integer","title":"Page"},"limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Limit"},"page_size":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Page Size"},"hasNextPage":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Hasnextpage"},"cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Cursor"}},"type":"object","required":["page","limit","page_size","hasNextPage","cursor"],"title":"MetadataResponse"},"DatasetResponse":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Description"},"earliest_available_time_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Earliest Available Time Utc"},"latest_available_time_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Latest Available Time Utc"},"source":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source"},"last_checked_time_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Checked Time Utc"},"primary_key_columns":{"anyOf":[{"items":{"type":"string"},"type":"array"},{"type":"null"}],"title":"Primary Key Columns"},"publish_time_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publish Time Column"},"time_index_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Time Index Column"},"subseries_index_column":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Subseries Index Column"},"all_columns":{"anyOf":[{"items":{"$ref":"#/components/schemas/ColumnResponse"},"type":"array"},{"type":"null"}],"title":"All Columns"},"number_of_rows_approximate":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Number Of Rows Approximate"},"table_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Table Type"},"is_in_snowflake":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is In Snowflake"},"data_frequency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Data Frequency"},"source_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Source Url"},"publication_frequency":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Publication Frequency"},"is_published":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Published"},"created_at_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Created At Utc"},"status":{"anyOf":[{"$ref":"#/components/schemas/DatasetStatusEnum"},{"type":"null"}]},"popularity_rank":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Popularity Rank"}},"type":"object","required":["id","name","description","earliest_available_time_utc","latest_available_time_utc","source","last_checked_time_utc","primary_key_columns","publish_time_column","time_index_column","subseries_index_column","all_columns","number_of_rows_approximate","table_type","is_in_snowflake","data_frequency","source_url","publication_frequency","is_published","created_at_utc","status"],"title":"DatasetResponse"},"ColumnResponse":{"properties":{"name":{"type":"string","title":"Name"},"type":{"type":"string","title":"Type"},"is_numeric":{"type":"boolean","title":"Is Numeric"},"is_date":{"type":"boolean","title":"Is Date","default":false},"is_datetime":{"type":"boolean","title":"Is Datetime"}},"type":"object","required":["name","type","is_numeric","is_datetime"],"title":"ColumnResponse"},"DatasetStatusEnum":{"type":"string","enum":["retired","active","deprecated"],"title":"DatasetStatusEnum"},"CSVResponse":{"properties":{"file":{"anyOf":[{"$ref":"#/components/schemas/FileResponseData"},{"type":"null"}],"description":"The CSV data as a bytes object, a string, or a StreamingResponse object."},"content_type":{"type":"string","title":"Content Type","description":"The content type of the response.","default":"text/csv"}},"type":"object","title":"CSVResponse"},"FileResponseData":{"properties":{"media_type":{"type":"string","title":"Media Type"},"content":{"anyOf":[{"type":"string","format":"binary"},{"type":"string"}],"title":"Content"}},"type":"object","required":["media_type","content"],"title":"FileResponseData"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}}} ``` --- # Agent Instructions: 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: ``` GET https://docs.gridstatus.io/developers/api-reference/query-data.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.