Skip to main content
GET
List programs

Authorizations

Authorization
string
header
required

Your Leap API key as a Bearer token. Send it in the Authorization header: Authorization: Bearer <api-key>.

Query Parameters

filter
string

Comma-separated field=value pairs, combined with AND. Supported fields: program_type, transmission_region, enabled, device_category, customer_classification and state. For example, filter=program_type=VPP,enabled=true returns the enabled programs that put a device under control.

An unrecognised field returns 400. enabled must be true or false; anything else returns 400. A pair with no = is ignored, so filter=VPP returns the unfiltered catalog. A filter over 500 characters returns 400.

With no enabled filter the response mixes enabled and disabled programs, and each row carries its own enabled flag.

Repeat device_category or customer_classification to match any of several values: device_category=ev_charger,device_category=solar_storage matches either. A LEAP_DEFINITIONS program that names no device category or classification matches every value. Every other field keeps its last value if repeated.

state matches a program's own state when it has one. Otherwise it matches the state Leap records for each utility the program serves.

Comparisons for device_category, customer_classification, state and enabled ignore case. Send program_type and transmission_region in upper case, such as VPP and CAISO.

q
string

Free-text search over each program's label, program_identifier and metadata.operator_name. Matching is case-insensitive and finds the text anywhere in those fields. Every word must match, so adding words narrows the result. Combines with filter and exclude_source.

A value over 200 characters returns 400. Leap reads the first 10 words, and the first 64 characters of each.

Minimum string length: 1
include_facets
boolean
default:false

Set to true to add a facets object to the response. It counts the programs matching your filter, q and exclude_source across every page. It also breaks them down by device category, customer classification, state and program type.

Send it on the first page only: a request with both include_facets=true and a page_token returns 400. The counts describe the whole filtered listing, so they are the same on every page. Defaults to false.

exclude_source
string

Comma-separated program sources to leave out: LEAP_DEFINITIONS, INCENTIVES_DB or PARTNER_OFFER. For example, exclude_source=PARTNER_OFFER lists catalog programs without any partner offers. An unrecognised value returns 400, and so does a value over 200 characters.

The exclusion applies to the listed programs and to the facets counts alike. Omit it to include every source.

page_token
string

Cursor from a previous response's next_page_token. Follow it until it is absent to walk the whole catalog. Replay a token only with the filter that produced it. Programs are ordered by program_identifier, so a program added below your cursor part-way through a walk is missed rather than duplicated. This route pages with page_size and page_token only: limit and offset return 400.

page_size
integer
default:50

Rows per page. Defaults to 50 and is capped at 200; a larger value is clamped rather than rejected.

Response

Successfully retrieved programs

One page of catalog programs, plus the cursor for the next page.

data
object[]
next_page_token
string

Cursor for the next page, absent on the last page. Pass it back as page_token, with the same filter that produced it.

facets
object

Counts that describe the whole filtered listing, not only the page in data. Present only when the request sets include_facets=true.

Each per-value map is counted without its own filter field. A dropdown can then show what choosing another value would return. For example, by_state ignores your state filter and applies every other one. The maps therefore don't add up to total.