TABLE OF CONTENTS
Overview
Stack Overflow Internal API v3 enables you to interact with your Stack Overflow Internal site programmatically with external scripts, reporting tools, and automated workflows.
How you authenticate into and access API v3 depends on your Stack Overflow Internal version. Follow the appropriate link below to learn more.
Stack Internal Basic, Business API v3
Stack Internal Enterprise API v3
Stack Internal Free has no API access. Stack Internal Basic offers read-only API v3 access, while Stack Internal Business and Enterprise can use API v3 to read and write. Find your plan.
In addition to the general API support documentation, your site has interactive documentation with definitions for all API v3 methods and data models. This interactive documentation system (Swagger UI) allows you to test API calls and view returned data in a convenient web interface with no API implementation required. For more information, see the "Interactive API v3 documentation" section of the relevant document linked above.
To avoid having the API block or throttle your requests, make sure each API request includes a User-Agent header. See the "User-agent header" section below.
Throttling
Stack Overflow Internal API v3 uses short-term burst throttling and long-term token-bucket throttling to prevent abuse and protect performance. These controls limit how quickly and frequently you can make requests.
Burst throttle rate limiter
The burst throttle rate limiter engages when an access token or application key makes too many requests during a brief window of time. The default for this limiter is 50 requests in a two-second interval.
The burst throttle rate limiter returns two headers with information about throttling status:
- x-burst-throttle-calls-left The number of calls left in the time window before the throttle begins rejecting API calls.
- x-burst-throttle-seconds-until-full The number of seconds left in the throttle time window.
Token bucket rate limiter
The token bucket rate limiter manages a bucket of request tokens; each access request consumes one token from the bucket. When the bucket is empty, API v3 rejects additional requests until it refills. API v3 refills the bucket at a set rate and stops adding tokens when the bucket is full.
The default maximum is 5,000 tokens in the bucket, and the default refill rate is 100 tokens every 60 seconds. This permits about 144,000 requests in a day, making this the practical request limit for a default API application.
For application key requests, the bucket tracks token usage per API application. For access token requests, the bucket tracks requests per API application per user.
API v3 responses include three headers with information about the token bucket rate limiter status:
- x-token-bucket-calls-left The number of tokens currently in the bucket.
- x-token-bucket-seconds-until-full The number of seconds until the token bucket is full (assuming no additional API calls).
- x-token-bucket-seconds-until-next-refill The number of seconds until API v3 adds the next batch of tokens to the bucket.
Daily API request limits
Daily request limits set the maximum number of requests an API application will allow in a 24-hour period. Each API application has a separate daily request pool for its key and for each authenticated user who accesses it with a token. These pools do not affect each other.
Application key daily limit (global)
Requests using an application key contribute to the application's daily access key request total. When this total hits the daily limit, API v3 blocks further requests that use that application key (token access is unaffected). All requests made with that application key (from all users) contribute to this total.
Access token daily limit (per user)
Requests using an access token count toward that user's request total per application. When that total exceeds the application's daily limit, API v3 will block requests from that user for that application. Each authenticated user also has a maximum of 150,000 requests per day across all API applications they access with tokens. API v3 does not (cannot) track per-user application key requests, so it enforces no daily key usage limit per user.
API v3 responses include three headers with information about the daily API request limit:
x-rate-limit The daily request limit.
x-rate-limit-calls-left The number of requests remaining.
x-rate-limit-seconds-until-reset Seconds until the daily limit resets.
Throttling and daily limits chart
| Access method | Request-rate controls | Application daily request limit | User daily request limit |
|---|---|---|---|
| Application key | Burst and token-bucket throttles | Admin-configured daily limit (all requests made with its API key) | none |
| Access token | Burst and token-bucket throttles | Per app per user | 150,000 requests across all apps |
API write operations
Using the Stack Overflow API to add or edit content involves additional considerations and concerns. If not done with care, automating the addition of new content can actually decrease user engagement. Learn more about using the API to write data in the Use the Write API article.
User-Agent header
To avoid having the API block or throttle your requests, make sure each API request includes a User-Agent header. The User-Agent string should be unique and descriptive. We recommend including your app name, URL, and email address in this format:
User-Agent: your_app_name/1.0 (http://your-app-url.com; your-email@somewhere.com)