Globalping Limits API

openapi: 3.2.0
info:
  title: Globalping Limits API
  summary: The public Globalping API.
  description: 'The Globalping API allows you to monitor, debug, and benchmark your internet infrastructure using a globally distributed network of probes.

    The supported test types are ping, traceroute, MTR, DNS resolve, and HTTP.


    The API is public, free to use, and doesn''t require authentication, but it implements rate limits to ensure fair usage and reliability.

    Authenticated users get higher free limits and may run additional tests by spending credits.

    Sign up on the Globalping Dashboard to enjoy the higher limits.


    Root endpoint: https://api.globalping.io


    ## Limits and credits


    | Operation | Unauthenticated user | Authenticated user |

    |---|---|---|

    | **Measurements** |||

    | Create a measurement | 250 free tests/hour

    50 probes/measurement | 500 free tests/hour*

    500 probes/measurement |

    | Get a measurement by ID | 2 requests/second/measurement | 2 requests/second/measurement |

    | **Probes** |||

    | List probes currently online | no limit | no limit |

    | **Limits** |||

    | Get current rate limits | no limit | no limit |


    \*Additional measurements may be created by spending credits. Each test above the limit costs one credit. Learn more about credits on the Globalping website.


    ## Client guidelines


    If you''re implementing an application that interacts with the API, please refer to the "Client guidelines"

    section in the description of each endpoint. This way, you can provide the best UX and reduce the likelihood

    of your app breaking in the future.


    ### General guidelines for non-browser-based apps:


    - Set a `User-Agent` header. We recommend that you follow the format and approach used here.

    - Set an `Accept-Encoding` header with a value of either `br` (preferred) or `gzip`, depending on what your client can support. Compression has a significant impact on the response size.

    - Implement ETag-based client-side caching using the `ETag`/`If-None-Match` headers when requesting the measurement status.'
  version: 1.0.0
  termsOfService: https://github.com/jsdelivr/globalping
  contact:
    url: https://github.com/jsdelivr/globalping/issues
    email: d@globalping.io
  license:
    name: Open Software License 3.0
    identifier: OSL-3.0
servers:
- url: https://api.globalping.io
security: []
tags:
- name: Limits
  description: Inspect the current user's or IP address's rate limits and credits.
paths:
  /v1/limits:
    get:
      summary: Get current rate limits
      operationId: getLimits
      description: Returns rate limits for the current user (if authenticated) or IP address (if not authenticated).
      responses:
        '200':
          $ref: '#/components/responses/limits'
      tags:
      - Limits
      security:
      - {}
      - BearerAuth: []
      - OAuth2: []
components:
  examples:
    nonAuthenticatedLimits:
      summary: non authenticated
      value:
        rateLimit:
          measurements:
            create:
              type: ip
              limit: 250
              remaining: 245
              reset: 3599
    authenticatedLimits:
      summary: authenticated
      value:
        rateLimit:
          measurements:
            create:
              type: user
              limit: 500
              remaining: 490
              reset: 3599
        credits:
          remaining: 1000
  schemas:
    RateLimitType:
      type: string
      description: Type of the rate limit.
      enum:
      - ip
      - user
    RateLimitDetails:
      type: object
      required:
      - type
      - limit
      - remaining
      - reset
      properties:
        type:
          $ref: '#/components/schemas/RateLimitType'
        limit:
          type: integer
          description: The number of rate limit points available in a given time window.
        remaining:
          type: integer
          description: The number of rate limit points remaining in the current time window.
        reset:
          type: integer
          description: The number of seconds until the limit resets.
    Limits:
      type: object
      required:
      - rateLimit
      properties:
        rateLimit:
          type: object
          description: Object containing rate limits information.
          required:
          - measurements
          properties:
            measurements:
              type: object
              description: Measurements rate limits.
              required:
              - create
              properties:
                create:
                  allOf:
                  - $ref: '#/components/schemas/RateLimitDetails'
                  - description: Rate limit for creating measurements.
        credits:
          type: object
          description: Object containing credits information (only for authenticated requests).
          properties:
            remaining:
              type: integer
              description: The number of user's remaining credits.
  responses:
    limits:
      description: 'A successful request returns status `200 OK` and a body containing information about the current rate limits and user credits.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Limits'
          examples:
            noAuthLimits:
              $ref: '#/components/examples/nonAuthenticatedLimits'
            authLimits:
              $ref: '#/components/examples/authenticatedLimits'
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: 'For end users - generate a token in the [Globalping Dashboard](https://dash.globalping.io/tokens) and send it with your requests to get higher limits.

        '
    OAuth2:
      type: oauth2
      flows:
        authorizationCode:
          authorizationUrl: https://auth.globalping.io/oauth/authorize
          tokenUrl: https://auth.globalping.io/oauth/token
          refreshUrl: https://auth.globalping.io/oauth/token
          scopes:
            measurements: execute measurements under your account
      description: 'For developers building applications on top of Globalping - if you want to allow end users to sign in and run measurements under their own accounts,

        we can provide OAuth2 access. Please e-mail d@globalping.io for more information.

        '