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: HubSpot
providerId: hubspot
created: '2026-05-04'
# Provenance stamped 2026-08-11: this artifact was written by the API Evangelist
# bulk sweep dated 2026-05-04, not harvested from the provider. See roadmap#35.
method: generated
modified: '2026-05-04'
reconciled: true
tags:
  - Rate Limiting
  - CRM
description: HubSpot REST API rate limits per app per portal. Limits scale with tier; Enterprise has higher
  daily caps.
sources:
  - https://www.hubspot.com/pricing/marketing
  - https://developers.hubspot.com/docs/guides/apps/api-usage/usage-details
headers:
  dailyLimit: X-HubSpot-RateLimit-Daily
  dailyRemaining: X-HubSpot-RateLimit-Daily-Remaining
  secondLimit: X-HubSpot-RateLimit-Secondly
  secondRemaining: X-HubSpot-RateLimit-Secondly-Remaining
responseCodes:
  throttled: 429
limits:
  - name: Free / Starter
    scope: app/portal
    metric: requests_per_day
    limit: 250000
    timeFrame: day
  - name: Free / Starter (burst)
    scope: app/portal
    metric: requests_per_10s
    limit: 100
    timeFrame: 10 seconds
  - name: Professional / Enterprise
    scope: app/portal
    metric: requests_per_day
    limit: 500000
    timeFrame: day
  - name: Professional / Enterprise (burst)
    scope: app/portal
    metric: requests_per_10s
    limit: 150
    timeFrame: 10 seconds
  - name: Search API
    scope: app/portal
    metric: requests_per_second
    limit: 4
    timeFrame: second
  - name: Batch endpoints
    scope: app/portal
    metric: objects_per_request
    limit: 100
    timeFrame: request

# --- Verification pass 2026-08-13 (enrichment pipeline) ---
verification:
  checked: '2026-08-13'
  docs_url: https://developers.hubspot.com/docs/guides/apps/api-usage/usage-details
  docs_status: gated
  docs_detail: >-
    HubSpot's API usage/limits reference 307-redirects to
    https://app.hubspot.com/myaccounts (a HubSpot login), so the tier numbers
    above could NOT be re-verified against the provider and remain
    method: generated rather than being promoted to searched.
  live_probe:
    url: https://api.hubapi.com/crm/v3/objects/contacts?limit=1
    http_status: 401
    rate_limit_headers_present: false
    note: >-
      HubSpot's budget is scoped per app per portal, so X-HubSpot-RateLimit-*
      headers are only emitted on authenticated responses. Their absence on an
      anonymous 401 is expected and is not evidence the headers do not exist.
  exhausted_status: 429
  retry_after:
    header: Retry-After
    documented_for: >-
      HTTP 477 (migration in progress), per the public error-handling reference.
      Not documented for 429.