> 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/api-reference/outages.md).

# Outages

## List Active Outages

> List scheduled transmission outages that overlap a time window.

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/outages/{market_id}/active":{"get":{"tags":["Outages"],"summary":"List Active Outages","description":"List scheduled transmission outages that overlap a time window.","operationId":"list_active_outages_v1_outages__market_id__active_get","parameters":[{"name":"market_id","in":"path","required":true,"schema":{"type":"string","description":"Market id (e.g. pjm). Determines outage + coordinates datasets.","title":"Market Id"},"description":"Market id (e.g. pjm). Determines outage + coordinates datasets."},{"name":"start_time","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Inclusive start of a half-open window (ISO 8601, UTC). Use with end_time. Tickets whose displayed interval overlaps [start_time, end_time) are returned. Also the reconstruction as-of cutoff (version/change times <= start_time).","title":"Start Time"},"description":"Inclusive start of a half-open window (ISO 8601, UTC). Use with end_time. Tickets whose displayed interval overlaps [start_time, end_time) are returned. Also the reconstruction as-of cutoff (version/change times <= start_time)."},{"name":"end_time","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Exclusive end of a half-open window (ISO 8601, UTC).","title":"End Time"},"description":"Exclusive end of a half-open window (ISO 8601, UTC)."},{"name":"start_date","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Optional inclusive lower bound on the ticket's displayed current_interval_start_utc (ISO 8601, UTC). When omitted, outages that started at any time are included.","title":"Start Date"},"description":"Optional inclusive lower bound on the ticket's displayed current_interval_start_utc (ISO 8601, UTC). When omitted, outages that started at any time are included."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100000,"minimum":1,"description":"Maximum number of tickets to return. When more tickets match, truncated is true and tickets is trimmed to this limit. Each returned ticket includes its full equipment list.","default":50000,"title":"Limit"},"description":"Maximum number of tickets to return. When more tickets match, truncated is true and tickets is trimmed to this limit. Each returned ticket includes its full equipment list."},{"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":"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":{"$ref":"#/components/schemas/PJMActiveOutagesResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"PJMActiveOutagesResponse":{"properties":{"truncated":{"type":"boolean","title":"Truncated"},"tickets":{"items":{"$ref":"#/components/schemas/PJMActiveOutageTicket"},"type":"array","title":"Tickets"}},"type":"object","required":["truncated","tickets"],"title":"PJMActiveOutagesResponse"},"PJMActiveOutageTicket":{"properties":{"ticket":{"type":"integer","title":"Ticket"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"outage_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Outage Type"},"version_time_utc":{"type":"string","format":"date-time","title":"Version Time Utc"},"current_interval_start_utc":{"type":"string","format":"date-time","title":"Current Interval Start Utc"},"current_interval_end_utc":{"type":"string","format":"date-time","title":"Current Interval End Utc"},"causes":{"items":{"type":"string"},"type":"array","title":"Causes"},"equipment":{"items":{"$ref":"#/components/schemas/PJMActiveOutageEquipment"},"type":"array","title":"Equipment"}},"type":"object","required":["ticket","version_time_utc","current_interval_start_utc","current_interval_end_utc","causes","equipment"],"title":"PJMActiveOutageTicket"},"PJMActiveOutageEquipment":{"properties":{"zone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zone"},"facility_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Facility Name"},"equipment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Equipment Type"},"station_1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Station 1"},"station_2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Station 2"},"from_substation":{"anyOf":[{"$ref":"#/components/schemas/SubstationLocation"},{"type":"null"}]},"to_substation":{"anyOf":[{"$ref":"#/components/schemas/SubstationLocation"},{"type":"null"}]},"voltage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Voltage"},"equipment_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Equipment Name"},"switching_action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Switching Action"},"interval_start_utc":{"type":"string","format":"date-time","title":"Interval Start Utc"},"interval_end_utc":{"type":"string","format":"date-time","title":"Interval End Utc"}},"type":"object","required":["interval_start_utc","interval_end_utc"],"title":"PJMActiveOutageEquipment"},"SubstationLocation":{"properties":{"latitude":{"type":"number","title":"Latitude"},"longitude":{"type":"number","title":"Longitude"},"name":{"type":"string","title":"Name"}},"type":"object","required":["latitude","longitude","name"],"title":"SubstationLocation","description":"Lat/lon and display name for a substation."},"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"}}}}
```

## Search Pjm Outage Tickets

> Search present PJM tickets whose latest reported start falls in a window.

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/outages/pjm/search":{"get":{"tags":["Outages"],"summary":"Search Pjm Outage Tickets","description":"Search present PJM tickets whose latest reported start falls in a window.","operationId":"search_pjm_outage_tickets_v1_outages_pjm_search_get","parameters":[{"name":"start_time","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Inclusive start of a half-open window (ISO 8601, UTC). Tickets whose latest reported outage start falls in [start_time, end_time) are returned.","title":"Start Time"},"description":"Inclusive start of a half-open window (ISO 8601, UTC). Tickets whose latest reported outage start falls in [start_time, end_time) are returned."},{"name":"end_time","in":"query","required":true,"schema":{"type":"string","format":"date-time","description":"Exclusive end of a half-open window (ISO 8601, UTC).","title":"End Time"},"description":"Exclusive end of a half-open window (ISO 8601, UTC)."},{"name":"search","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":200},{"type":"null"}],"description":"Case-insensitive match on ticket number, facility name, equipment name, or station name.","title":"Search"},"description":"Case-insensitive match on ticket number, facility name, equipment name, or station name."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":1000,"minimum":1,"description":"Maximum number of tickets to return.","default":1000,"title":"Limit"},"description":"Maximum number of tickets to return."},{"name":"min_voltage_kv","in":"query","required":false,"schema":{"anyOf":[{"type":"integer","minimum":0},{"type":"null"}],"description":"Keep tickets that have present equipment at or above this voltage (kV). Equipment with unknown voltage does not match.","title":"Min Voltage Kv"},"description":"Keep tickets that have present equipment at or above this voltage (kV). Equipment with unknown voltage does not match."},{"name":"zones","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated PJM zone codes. Empty means all zones.","title":"Zones"},"description":"Comma-separated PJM zone codes. Empty means all zones."},{"name":"equipment_types","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Comma-separated equipment types (LINE, XFMR, GEN, PS, CAP, BRKR, OTHER). Empty means all types. OTHER matches unnamed or unrecognized types.","title":"Equipment Types"},"description":"Comma-separated equipment types (LINE, XFMR, GEN, PS, CAP, BRKR, OTHER). Empty means all types. OTHER matches unnamed or unrecognized types."},{"name":"open_closed","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Ticket equipment state: both, open, or closed. A ticket is open when any present equipment has an open switching action.","title":"Open Closed"},"description":"Ticket equipment state: both, open, or closed. A ticket is open when any present equipment has an open switching action."},{"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":"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":{"$ref":"#/components/schemas/PJMOutageSearchResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"PJMOutageSearchResponse":{"properties":{"results":{"items":{"$ref":"#/components/schemas/PJMOutageSearchHit"},"type":"array","title":"Results"}},"type":"object","required":["results"],"title":"PJMOutageSearchResponse"},"PJMOutageSearchHit":{"properties":{"ticket":{"type":"integer","title":"Ticket"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"open_closed":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Open Closed"},"outage_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Outage Type"},"report_time_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Report Time Utc"},"interval_start_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Interval Start Utc"},"interval_end_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Interval End Utc"},"facilities":{"items":{"type":"string"},"type":"array","title":"Facilities"},"equipment_names":{"items":{"type":"string"},"type":"array","title":"Equipment Names"},"stations":{"items":{"type":"string"},"type":"array","title":"Stations"}},"type":"object","required":["ticket","facilities","equipment_names","stations"],"title":"PJMOutageSearchHit"},"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"}}}}
```

## Get Pjm Outage Ticket Detail

> Return CDC histories for one PJM transmission outage ticket.\
> \
> Newest change or version first in each list. Tickets with no versions\
> return 404.

```json
{"openapi":"3.1.0","info":{"title":"Grid Status API","version":"1.3.0"},"servers":[{"url":"https://api.gridstatus.io/v1"}],"paths":{"/outages/pjm/{ticket_id}":{"get":{"tags":["Outages"],"summary":"Get Pjm Outage Ticket Detail","description":"Return CDC histories for one PJM transmission outage ticket.\n\nNewest change or version first in each list. Tickets with no versions\nreturn 404.","operationId":"get_pjm_outage_ticket_detail_v1_outages_pjm__ticket_id__get","parameters":[{"name":"ticket_id","in":"path","required":true,"schema":{"type":"integer","description":"PJM transmission outage ticket number.","title":"Ticket Id"},"description":"PJM transmission outage ticket number."},{"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":"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":{"$ref":"#/components/schemas/PJMOutageTicketResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"PJMOutageTicketResponse":{"properties":{"ticket":{"type":"integer","title":"Ticket"},"cause_changes":{"items":{"$ref":"#/components/schemas/PJMCauseChangeRow"},"type":"array","title":"Cause Changes"},"equipment_changes":{"items":{"$ref":"#/components/schemas/PJMEquipmentChangeRow"},"type":"array","title":"Equipment Changes"},"status_changes":{"items":{"$ref":"#/components/schemas/PJMStatusChangeRow"},"type":"array","title":"Status Changes"},"ticket_versions":{"items":{"$ref":"#/components/schemas/PJMOutageTicketVersionRow"},"type":"array","title":"Ticket Versions"},"window_changes":{"items":{"$ref":"#/components/schemas/PJMWindowChangeRow"},"type":"array","title":"Window Changes"}},"type":"object","required":["ticket","cause_changes","equipment_changes","status_changes","ticket_versions","window_changes"],"title":"PJMOutageTicketResponse","description":"CDC histories for one PJM transmission outage ticket."},"PJMCauseChangeRow":{"properties":{"change_time_utc":{"type":"string","format":"date-time","title":"Change Time Utc"},"ticket":{"type":"integer","title":"Ticket"},"cause":{"type":"string","title":"Cause"},"is_present":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Present"}},"type":"object","required":["change_time_utc","ticket","cause"],"title":"PJMCauseChangeRow"},"PJMEquipmentChangeRow":{"properties":{"change_time_utc":{"type":"string","format":"date-time","title":"Change Time Utc"},"ticket":{"type":"integer","title":"Ticket"},"zone":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Zone"},"facility_name":{"type":"string","title":"Facility Name"},"equipment_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Equipment Type"},"station_1":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Station 1"},"station_2":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Station 2"},"voltage":{"anyOf":[{"type":"number"},{"type":"null"}],"title":"Voltage"},"equipment_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Equipment Name"},"switching_action":{"type":"string","title":"Switching Action"},"interval_start_utc":{"type":"string","format":"date-time","title":"Interval Start Utc"},"interval_end_utc":{"type":"string","format":"date-time","title":"Interval End Utc"},"is_present":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Present"},"from_substation":{"anyOf":[{"$ref":"#/components/schemas/SubstationLocation"},{"type":"null"}]},"to_substation":{"anyOf":[{"$ref":"#/components/schemas/SubstationLocation"},{"type":"null"}]}},"type":"object","required":["change_time_utc","ticket","facility_name","switching_action","interval_start_utc","interval_end_utc"],"title":"PJMEquipmentChangeRow"},"SubstationLocation":{"properties":{"latitude":{"type":"number","title":"Latitude"},"longitude":{"type":"number","title":"Longitude"},"name":{"type":"string","title":"Name"}},"type":"object","required":["latitude","longitude","name"],"title":"SubstationLocation","description":"Lat/lon and display name for a substation."},"PJMStatusChangeRow":{"properties":{"first_observed_time_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Observed Time Utc"},"ticket":{"type":"integer","title":"Ticket"},"status_time_utc":{"type":"string","format":"date-time","title":"Status Time Utc"},"status_sequence":{"type":"integer","title":"Status Sequence"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"}},"type":"object","required":["ticket","status_time_utc","status_sequence"],"title":"PJMStatusChangeRow"},"PJMOutageTicketVersionRow":{"properties":{"version_time_utc":{"type":"string","format":"date-time","title":"Version Time Utc"},"ticket":{"type":"integer","title":"Ticket"},"is_present":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Is Present"},"current_interval_start_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Current Interval Start Utc"},"current_interval_end_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Current Interval End Utc"},"status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Status"},"previous_status":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Previous Status"},"outage_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Outage Type"},"rtep":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Rtep"},"availability":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Availability"},"approval_risk":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Approval Risk"},"on_time":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"On Time"},"last_revised_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Revised Utc"},"last_evaluated_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Last Evaluated Utc"}},"type":"object","required":["version_time_utc","ticket"],"title":"PJMOutageTicketVersionRow","description":"One CDC revision of a PJM transmission outage ticket."},"PJMWindowChangeRow":{"properties":{"first_observed_time_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"First Observed Time Utc"},"ticket":{"type":"integer","title":"Ticket"},"revision_time_utc":{"type":"string","format":"date-time","title":"Revision Time Utc"},"revision_sequence":{"type":"integer","title":"Revision Sequence"},"interval_start_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Interval Start Utc"},"interval_end_utc":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Interval End Utc"}},"type":"object","required":["ticket","revision_time_utc","revision_sequence"],"title":"PJMWindowChangeRow"},"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
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/api-reference/outages.md?ask=<question>&goal=<endgoal>
```

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