specification: API Commons Rate Limits
specificationVersion: '0.1'
schema: https://raw.githubusercontent.com/api-evangelist/interface-research/main/schema/api-commons.yml#/$defs/RateLimits
provider: CMS Energy
providerId: cms-energy
created: '2026-05-04'
modified: '2026-09-06'
generated: '2026-09-06'
method: searched
source: https://utilityapi.com/docs/availability
reconciled: true
tags:
  - Electric
  - Energy
  - Green Button
  - Utility
  - Rate Limiting
description: >-
  Published rate limits for the CMS Energy / Consumers Energy API surface. The Green Button
  Connect My Data program publishes real, numeric guidance and a documented exhaustion signal;
  the first-party ArcGIS outage services publish a per-response record cap but no request rate.
notes: >-
  Supersedes the 2026-05-04 bulk-sweep placeholder, which recorded that no numeric limits were
  published. They are published — on the platform's availability page, which the Consumers
  Energy Green Button host links to as its API Documentation.
sources:
  - https://utilityapi.com/docs/availability
  - https://utilityapi.com/docs/greenbutton/api
  - https://www.consumersenergy.com/arcgispublic/rest/services/CEOutageMap/MapServer?f=json
responseCodes:
  throttled: 429
  serviceUnavailable: 503
  asyncDeferred: 202
headers:
  request: []
  response:
    - name: Retry-After
      applies_to: [429, 202]
      detail: >-
        Carries the wait before retrying. On a 202 it says how long to wait while the payload is
        cached asynchronously.
      source: https://utilityapi.com/docs/greenbutton/api
  budget_headers_published: false
  budget_note: >-
    No RateLimit-* or X-RateLimit-* headers are documented, so an agent cannot see remaining
    budget — only that it has been exhausted.
limits:
  - id: bill-and-interval-downloads
    scope: per-account
    surface: Consumers Energy GBCMD JSON API (https://utilityapi.com/api/v2)
    operations: [listBills, listIntervals, bill downloads, interval downloads]
    window: 1 minute
    limit: 1
    unit: requests
    enforcement: soft
    detail: >-
      "please try to not GET request bill and interval downloads more than 1/per minute" —
      published as a rule of thumb, enforced by throttling when abused rather than as a hard quota.
    source: https://utilityapi.com/docs/availability
  - id: all-other-requests
    scope: per-account
    surface: Consumers Energy GBCMD JSON API (https://utilityapi.com/api/v2)
    operations: [all other GET and POST]
    window: 1 second
    limit: 1
    unit: requests
    enforcement: soft
    detail: '"all other GET and POST requests 1/per second".'
    source: https://utilityapi.com/docs/availability
  - id: arcgis-max-record-count
    scope: per-request
    surface: Consumers Energy ArcGIS REST services (https://www.consumersenergy.com/arcgispublic/rest)
    window: per response
    limit: 1000
    unit: features
    enforcement: hard
    detail: >-
      maxRecordCount 1000 on both CEOutageMap/MapServer and ServiceDashboard/MapServer|FeatureServer.
      A per-response cap, not a request rate; page with resultRecordCount / resultOffset.
    source: https://www.consumersenergy.com/arcgispublic/rest/services/CEOutageMap/MapServer?f=json
  - id: arcgis-request-rate
    scope: per-client
    surface: Consumers Energy ArcGIS REST services
    window: null
    limit: null
    unit: null
    enforcement: undocumented
    detail: >-
      No request rate limit is published for the anonymous ArcGIS surface. robots.txt disallows
      /arcgispublic/* to crawlers, which is a crawl directive rather than a rate limit.
    source: https://www.consumersenergy.com/robots.txt
limit_count: 3