MongoDB Rate Limiting API

openapi: 3.0.1
info:
  description: "The MongoDB Atlas Administration API allows developers to manage all components in MongoDB Atlas.\n\nThe Atlas Administration API supports OAuth2 Service Accounts and HTTP Digest-based API keys. Service accounts are the recommended authentication method and API keys are considered a legacy option.\n\nTo authenticate with a Service Account, first exchange its client ID and secret for an access token using the OAuth 2.0 Client Credentials flow. Atlas provides a token endpoint at `POST https://cloud.mongodb.com/api/oauth/token`, which returns a Bearer token that is reusable and valid for 1 hour (3600 seconds).\n\nFor example, to [return a list of your organizations](https://www.mongodb.com/docs/api/doc/atlas-admin-api-v2/operation/operation-listorgs) with [cURL](https://en.wikipedia.org/wiki/CURL), first generate an access token and then use that token to call the same Atlas Administration API endpoint shown in the current example:\n\n```\nACCESS_TOKEN=$(curl -fsS --request POST https://cloud.mongodb.com/api/oauth/token \\\n  --header \"Authorization: Basic $(printf '%s' \"${CLIENT_ID}:${CLIENT_SECRET}\" | base64 | tr -d '\\n')\" \\\n  --header \"Content-Type: application/x-www-form-urlencoded\" \\\n  --header \"Accept: application/json\" \\\n  --data \"grant_type=client_credentials\" | jq -r '.access_token')\n\ncurl --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n  --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n  -X GET \"https://cloud.mongodb.com/api/atlas/v2/orgs?pretty=true\"\n```\n\nIf your organization requires an IP access list for the Atlas Administration API, the token can be created from any IP address, but the API call that uses the token must originate from an allowed IP.\n\nTo learn more, see [Get Started with the Atlas Administration API](https://www.mongodb.com/docs/atlas/configure-api-access/). For support, see [MongoDB Support](https://www.mongodb.com/support/get-started).\n\nYou can also explore the various endpoints available through the Atlas Administration API in MongoDB's [Postman workspace](https://www.postman.com/mongodb-devrel/workspace/mongodb-atlas-administration-apis/) (requires a Postman account)."
  license:
    name: CC BY-NC-SA 3.0 US
    url: https://creativecommons.org/licenses/by-nc-sa/3.0/us/
  termsOfService: https://www.mongodb.com/mongodb-management-service-terms-and-conditions
  title: MongoDB Atlas Administration Access Tracking Rate Limiting API
  version: '2.0'
  x-xgen-sha: 3d70e065843c008b9871ea7836c98c9de6f202f9
servers:
- url: https://cloud.mongodb.com
security:
- ServiceAccounts: []
- DigestAuth: []
tags:
- description: Returns details about rate limit policies for the Atlas Administration API.
  externalDocs:
    description: Atlas API Rate Limits documentation
    url: http://dochub.mongodb.org/core/atlas-api-rate-limit
  name: Rate Limiting
paths:
  /api/atlas/v2/rateLimits:
    get:
      description: Get all rate limits for all v2 Atlas Administration API endpoint sets.
      operationId: listRateLimits
      parameters:
      - $ref: '#/components/parameters/itemsPerPage'
      - $ref: '#/components/parameters/pageNum'
      - $ref: '#/components/parameters/pretty'
      - $ref: '#/components/parameters/envelope'
      - description: Unique 24-hexadecimal digit string that identifies the Atlas Project to request rate limits for. When this parameter is provided, only group scoped endpoint sets are returned and the limits returned are applicable to the specified project. The requesting user must have the Project Read Only role for the specified project.
        in: query
        name: groupId
        schema:
          example: 32b6e34b3d91647abb20e7b8
          pattern: ^([a-f0-9]{24})$
          type: string
      - description: Unique 24-hexadecimal digit string that identifies the Atlas Organization to request rate limits for. When this parameter is provided, only organization scoped endpoint sets are returned and the limits returned are applicable to the specified organization. The requesting user must have the Organization Read Only role for the specified organization.
        in: query
        name: orgId
        schema:
          example: 32b6e34b3d91647abb20e7b8
          pattern: ^([a-f0-9]{24})$
          type: string
      - description: A string that identifies the Atlas user to request rate limits for. The ID can for example be the Service Account Client ID or the API Public Key. When this parameter is provided, only user scoped endpoint sets are returned and the limits returned are applicable to the specified user. The requesting user must be the same as the specified user.
        in: query
        name: userId
        schema:
          example: mdb_sa_id_1234567890abcdef12345678
          type: string
      - description: An IP address to request rate limits for. When this parameter is provided, only IP scoped endpoint sets are returned and the limits returned are applicable to the specified IP address. The requesting user must have the same IP address as the one provided in the request.
        in: query
        name: ipAddress
        schema:
          example: 127.0.0.1
          pattern: ^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$)){4}|([0-9a-f]{1,4}:){7}[0-9a-f]{1,4}$
          type: string
      - description: Filters the returned endpoint sets by the provided endpoint set name. Multiple names may be provided, for example `/rateLimits?name=Name1&name=Name2`. For names that use spaces, replace the space with its URL-encoded value (`%20`).
        in: query
        name: name
        schema:
          example: Rate Limits Inspection
          type: string
      - description: Filters the returned endpoint sets by the provided endpoint path. Multiple paths may be provided, for example `/rateLimits?endpointPath=%2Fapi%2Fatlas%2Fv2%2Fclusters&endpointPath=%2Fapi%2Fatlas%2Fv2%2Fgroups%2F%7BgroupId%7D%2F`. Replace `/`, `{` and `}` with their URL-encoded values (`%2F`, `%7B` and `%7D` respectively).
        in: query
        name: endpointPath
        schema:
          example: /api/atlas/v2/clusters
          type: string
      responses:
        '200':
          content:
            application/vnd.atlas.2025-03-12+json:
              schema:
                $ref: '#/components/schemas/PaginatedRateLimitEndpointSets'
              x-xgen-version: '2025-03-12'
          description: OK
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/HeaderRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/HeaderRateLimitRemaining'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalServerError'
      summary: Return All Rate Limits
      tags:
      - Rate Limiting
      x-codeSamples:
      - lang: cURL
        label: Atlas CLI
        source: atlas api rateLimiting listRateLimits --help
      - lang: go
        label: Go
        source: "import (\n\t\"os\"\n\t\"context\"\n\t\"log\"\n\tsdk \"go.mongodb.org/atlas-sdk/v20250312001/admin\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclientID := os.Getenv(\"MONGODB_ATLAS_CLIENT_ID\")\n\tclientSecret := os.Getenv(\"MONGODB_ATLAS_CLIENT_SECRET\")\n\n\t// See https://dochub.mongodb.org/core/atlas-go-sdk-oauth\n\tclient, err := sdk.NewClient(sdk.UseOAuthAuth(clientID, clientSecret))\n\n\tif err != nil {\n\t\tlog.Fatalf(\"Error: %v\", err)\n\t}\n\n\tparams = &sdk.ListRateLimitsApiParams{}\n\tsdkResp, httpResp, err := client.RateLimitingApi.\n\t\tListRateLimitsWithParams(ctx, params).\n\t\tExecute()\n}\n"
      - lang: cURL
        label: curl (Service Accounts)
        source: "curl --include --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n  --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n  -X GET \"https://cloud.mongodb.com/api/atlas/v2/rateLimits?pretty=true\""
      - lang: cURL
        label: curl (Digest)
        source: "curl --user \"${PUBLIC_KEY}:${PRIVATE_KEY}\" \\\n  --digest --include \\\n  --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n  -X GET \"https://cloud.mongodb.com/api/atlas/v2/rateLimits?pretty=true\""
      x-xgen-docs-url: https://mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Rate-Limiting/operation/listRateLimits
  /api/atlas/v2/rateLimits/{endpointSetId}:
    get:
      description: Get one rate limit endpoint set.
      operationId: getRateLimit
      parameters:
      - description: The ID of the rate limit endpoint set.
        in: path
        name: endpointSetId
        required: true
        schema:
          example: rateLimitsInspection_group
          type: string
      - $ref: '#/components/parameters/pretty'
      - $ref: '#/components/parameters/envelope'
      - description: Unique 24-hexadecimal digit string that identifies the Atlas Project to request rate limits for. When this parameter is provided, the limits returned are applicable to the specified project. The requesting user must have the Project Read Only role for the specified project.
        in: query
        name: groupId
        schema:
          example: 32b6e34b3d91647abb20e7b8
          pattern: ^([a-f0-9]{24})$
          type: string
      - description: Unique 24-hexadecimal digit string that identifies the Atlas Organization to request rate limits for. When this parameter is provided, the limits returned are applicable to the specified organization. The requesting user must have the Organization Read Only role for the specified organization.
        in: query
        name: orgId
        schema:
          example: 32b6e34b3d91647abb20e7b8
          pattern: ^([a-f0-9]{24})$
          type: string
      - description: A string that identifies the Atlas user to request rate limits for. The ID can for example be the Service Account Client ID or the API Public Key. When this parameter is provided, the limits returned are applicable to the specified  user. The requesting user must be the same as the specified user.
        in: query
        name: userId
        schema:
          example: mdb_sa_id_1234567890abcdef12345678
          type: string
      - description: An IP address to request rate limits for. When this parameter is provided, the limits returned are applicable to the specified IP address. The requesting user must have the same IP address as the one provided in the request.
        in: query
        name: ipAddress
        schema:
          example: 127.0.0.1
          pattern: ^((25[0-5]|(2[0-4]|1\d|[1-9]|)\d)(\.(?!$)|$)){4}|([0-9a-f]{1,4}:){7}[0-9a-f]{1,4}$
          type: string
      responses:
        '200':
          content:
            application/vnd.atlas.2025-03-12+json:
              schema:
                $ref: '#/components/schemas/RateLimitEndpointSetResponse'
              x-xgen-version: '2025-03-12'
          description: OK
          headers:
            RateLimit-Limit:
              $ref: '#/components/headers/HeaderRateLimitLimit'
            RateLimit-Remaining:
              $ref: '#/components/headers/HeaderRateLimitRemaining'
        '400':
          $ref: '#/components/responses/badRequest'
        '401':
          $ref: '#/components/responses/unauthorized'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        '429':
          $ref: '#/components/responses/tooManyRequests'
        '500':
          $ref: '#/components/responses/internalServerError'
      summary: Return One Rate Limit
      tags:
      - Rate Limiting
      x-codeSamples:
      - lang: cURL
        label: Atlas CLI
        source: atlas api rateLimiting getRateLimit --help
      - lang: go
        label: Go
        source: "import (\n\t\"os\"\n\t\"context\"\n\t\"log\"\n\tsdk \"go.mongodb.org/atlas-sdk/v20250312001/admin\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclientID := os.Getenv(\"MONGODB_ATLAS_CLIENT_ID\")\n\tclientSecret := os.Getenv(\"MONGODB_ATLAS_CLIENT_SECRET\")\n\n\t// See https://dochub.mongodb.org/core/atlas-go-sdk-oauth\n\tclient, err := sdk.NewClient(sdk.UseOAuthAuth(clientID, clientSecret))\n\n\tif err != nil {\n\t\tlog.Fatalf(\"Error: %v\", err)\n\t}\n\n\tparams = &sdk.GetRateLimitApiParams{}\n\tsdkResp, httpResp, err := client.RateLimitingApi.\n\t\tGetRateLimitWithParams(ctx, params).\n\t\tExecute()\n}\n"
      - lang: cURL
        label: curl (Service Accounts)
        source: "curl --include --header \"Authorization: Bearer ${ACCESS_TOKEN}\" \\\n  --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n  -X GET \"https://cloud.mongodb.com/api/atlas/v2/rateLimits/{endpointSetId}?pretty=true\""
      - lang: cURL
        label: curl (Digest)
        source: "curl --user \"${PUBLIC_KEY}:${PRIVATE_KEY}\" \\\n  --digest --include \\\n  --header \"Accept: application/vnd.atlas.2025-03-12+json\" \\\n  -X GET \"https://cloud.mongodb.com/api/atlas/v2/rateLimits/{endpointSetId}?pretty=true\""
      x-xgen-docs-url: https://mongodb.com/docs/atlas/reference/api-resources-spec/v2/#tag/Rate-Limiting/operation/getRateLimit
components:
  responses:
    internalServerError:
      content:
        application/json:
          example:
            detail: (This is just an example, the exception may not be related to this endpoint)
            error: 500
            errorCode: UNEXPECTED_ERROR
            reason: Internal Server Error
          schema:
            $ref: '#/components/schemas/ApiError'
      description: Internal Server Error.
    forbidden:
      content:
        application/json:
          example:
            detail: (This is just an example, the exception may not be related to this endpoint)
            error: 403
            errorCode: CANNOT_CHANGE_GROUP_NAME
            reason: Forbidden
          schema:
            $ref: '#/components/schemas/ApiError'
      description: Forbidden.
    tooManyRequests:
      content:
        application/json:
          example:
            detail: (This is just an example, the exception may not be related to this endpoint)
            error: 429
            errorCode: RATE_LIMITED
            reason: Too Many Requests
          schema:
            $ref: '#/components/schemas/ApiError'
      description: Too Many Requests.
      headers:
        RateLimit-Limit:
          $ref: '#/components/headers/HeaderRateLimitLimit'
        RateLimit-Remaining:
          $ref: '#/components/headers/HeaderRateLimitRemaining'
        Retry-After:
          $ref: '#/components/headers/HeaderRetryAfter'
    unauthorized:
      content:
        application/json:
          example:
            detail: (This is just an example, the exception may not be related to this endpoint)
            error: 401
            errorCode: NOT_ORG_GROUP_CREATOR
            reason: Unauthorized
          schema:
            $ref: '#/components/schemas/ApiError'
      description: Unauthorized.
    badRequest:
      content:
        application/json:
          example:
            detail: (This is just an example, the exception may not be related to this endpoint) No provider AWS exists.
            error: 400
            errorCode: VALIDATION_ERROR
            reason: Bad Request
          schema:
            $ref: '#/components/schemas/ApiError'
      description: Bad Request.
    notFound:
      content:
        application/json:
          example:
            detail: (This is just an example, the exception may not be related to this endpoint) Cannot find resource AWS
            error: 404
            errorCode: RESOURCE_NOT_FOUND
            reason: Not Found
          schema:
            $ref: '#/components/schemas/ApiError'
      description: Not Found.
  schemas:
    Link:
      properties:
        href:
          description: Uniform Resource Locator (URL) that points another API resource to which this response has some relationship. This URL often begins with `https://cloud.mongodb.com/api/atlas`.
          example: https://cloud.mongodb.com/api/atlas
          type: string
        rel:
          description: Uniform Resource Locator (URL) that defines the semantic relationship between this resource and another API resource. This URL often begins with `https://cloud.mongodb.com/api/atlas`.
          example: self
          type: string
      type: object
    RateLimitEndpointSetEndpoint:
      properties:
        method:
          description: The HTTP method of the endpoint.
          enum:
          - GET
          - POST
          - PUT
          - DELETE
          - PATCH
          type: string
        path:
          description: The URL path of the endpoint.
          example: /api/atlas/v2/rateLimits
          type: string
      type: object
    ApiError:
      properties:
        badRequestDetail:
          $ref: '#/components/schemas/BadRequestDetail'
        detail:
          description: Describes the specific conditions or reasons that cause each type of error.
          type: string
        error:
          description: HTTP status code returned with this error.
          externalDocs:
            url: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status
          format: int32
          readOnly: true
          type: integer
        errorCode:
          description: Application error code returned with this error.
          readOnly: true
          type: string
        parameters:
          description: Parameters used to give more information about the error.
          items:
            type: object
          readOnly: true
          type: array
        reason:
          description: Application error message returned with this error.
          readOnly: true
          type: string
      required:
      - error
      - errorCode
      type: object
    RateLimitEndpointSetResponse:
      properties:
        capacity:
          $ref: '#/components/schemas/RateLimitEndpointSetCapacity'
        endpointSetId:
          description: The ID of the endpoint set.
          example: rateLimitsInspection_group
          type: string
        endpointSetName:
          description: The endpoint set name.
          example: Rate Limits Inspection
          type: string
        endpoints:
          description: A list of endpoints associated with the specified endpoint set.
          items:
            $ref: '#/components/schemas/RateLimitEndpointSetEndpoint'
          maxItems: 100
          type: array
          uniqueItems: true
        refillDurationSeconds:
          $ref: '#/components/schemas/RateLimitEndpointSetRefillDurationSeconds'
        refillRate:
          $ref: '#/components/schemas/RateLimitEndpointSetRefillRate'
        scope:
          description: The scope of the endpoint set.
          enum:
          - IP
          - GROUP
          - ORGANIZATION
          - USER
          type: string
      type: object
    BadRequestDetail:
      description: Bad request detail.
      properties:
        fields:
          description: Describes all violations in a client request.
          items:
            $ref: '#/components/schemas/FieldViolation'
          type: array
      readOnly: true
      type: object
    RateLimitEndpointSetCapacity:
      description: The rate limit capacity for the endpoint set.
      properties:
        defaultValue:
          description: The default request capacity of the endpoint set. Returned if there is a capacity override set for the requested entity.
          format: int64
          type: integer
        value:
          description: The applied request capacity of the endpoint set.
          format: int64
          type: integer
      type: object
    RateLimitEndpointSetRefillDurationSeconds:
      description: The rate limit refill duration for the endpoint set.
      properties:
        defaultValue:
          description: The default rate limit refill duration, in seconds, of the endpoint set. Returned if there is a rate limit refill duration override set for the requested entity.
          format: int64
          type: integer
        value:
          description: The applied rate limit refill duration of the endpoint set.
          format: int64
          type: integer
      type: object
    RateLimitEndpointSetRefillRate:
      description: The rate limit refill rate for the endpoint set.
      properties:
        defaultValue:
          description: The default rate limit refill rate of the endpoint set. Returned if there is a rate limit refill rate override set for the requested entity.
          format: int64
          type: integer
        value:
          description: The applied rate limit refill rate of the endpoint set.
          format: int64
          type: integer
      type: object
    FieldViolation:
      properties:
        description:
          description: A description of why the request element is bad.
          type: string
        field:
          description: A path that leads to a field in the request body.
          type: string
      required:
      - description
      - field
      type: object
    PaginatedRateLimitEndpointSets:
      description: A list of rate limit endpoint sets.
      properties:
        links:
          description: List of one or more Uniform Resource Locators (URLs) that point to API sub-resources, related API resources, or both. RFC 5988 outlines these relationships.
          externalDocs:
            description: Web Linking Specification (RFC 5988)
            url: https://datatracker.ietf.org/doc/html/rfc5988
          items:
            $ref: '#/components/schemas/Link'
          readOnly: true
          type: array
        results:
          description: List of returned documents that MongoDB Cloud provides when completing this request.
          items:
            $ref: '#/components/schemas/RateLimitEndpointSetResponse'
          readOnly: true
          type: array
        totalCount:
          description: Total number of documents available. MongoDB Cloud omits this value if `includeCount` is set to `false`. The total number is an estimate and may not be exact.
          format: int32
          minimum: 0
          readOnly: true
          type: integer
      required:
      - results
      type: object
  parameters:
    envelope:
      description: Flag that indicates whether Application wraps the response in an `envelope` JSON object. Some API clients cannot access the HTTP response headers or status code. To remediate this, set envelope=true in the query. Endpoints that return a list of results use the results object as an envelope. Application adds the status parameter to the response body.
      in: query
      name: envelope
      schema:
        default: false
        type: boolean
    pretty:
      description: Flag that indicates whether the response body should be in the prettyprint format.
      in: query
      name: pretty
      schema:
        default: false
        externalDocs:
          description: Prettyprint
          url: https://en.wikipedia.org/wiki/Prettyprint
        type: boolean
    itemsPerPage:
      description: Number of items that the response returns per page.
      in: query
      name: itemsPerPage
      schema:
        default: 100
        maximum: 500
        minimum: 1
        type: integer
    pageNum:
      description: Number of the page that displays the current set of the total objects that the response returns.
      in: query
      name: pageNum
      schema:
        default: 1
        minimum: 1
        type: integer
  headers:
    HeaderRetryAfter:
      description: The minimum time you should wait, in seconds, before retrying the API request. This header might be returned for 429 or 503 error responses.
      schema:
        type: integer
    HeaderRateLimitLimit:
      description: The maximum number of requests that a user can make within a specific time window.
      schema:
        type: integer
    HeaderRateLimitRemaining:
      description: The number of requests remaining in the current rate limit window before the limit is reached.
      schema:
        type: integer
  securitySchemes:
    DigestAuth:
      scheme: digest
      type: http
    ServiceAccounts:
      description: Learn more about [Service Accounts](https://www.mongodb.com/docs/atlas/api/service-accounts-overview).
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: https://cloud.mongodb.com/api/oauth/token
      type: oauth2
x-externalLinks:
- label: Back to Atlas Docs
  url: https://www.mongodb.com/docs/atlas/
- label: API Changelog
  url: https://www.mongodb.com/docs/atlas/reference/api-resources-spec/changelog/
x-topics:
- content: The MongoDB Atlas Administration API is rate limited. To learn more about rate limiting, see the [Atlas Documentation on Rate Limiting](http://dochub.mongodb.org/core/atlas-api-rate-limit)
  title: Rate Limiting