Globalping Probes API

openapi: 3.2.0
info:
  title: Globalping Probes 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: Probes
  description: Discover the probes currently available for measurements.
paths:
  /v1/probes:
    get:
      summary: List probes currently online
      operationId: listProbes
      description: 'Returns a list of all probes currently online and their metadata, such as location and assigned tags.


        > **Note**: Probes don''t expose unique IDs that would allow you to explicitly select them.

        Instead, specify the requested location or an ID of an existing measurement when creating new measurements.'
      responses:
        '200':
          $ref: '#/components/responses/probes200'
      tags:
      - Probes
components:
  schemas:
    RegionName:
      type: string
      description: 'A geographic region name based on UN [Standard Country or Area Codes for Statistical Use (M49)](https://unstats.un.org/unsd/methodology/m49/).

        '
      enum:
      - Northern Africa
      - Eastern Africa
      - Middle Africa
      - Southern Africa
      - Western Africa
      - Caribbean
      - Central America
      - South America
      - Northern America
      - Central Asia
      - Eastern Asia
      - South-eastern Asia
      - Southern Asia
      - Western Asia
      - Eastern Europe
      - Northern Europe
      - Southern Europe
      - Western Europe
      - Australia and New Zealand
      - Melanesia
      - Micronesia
      - Polynesia
    AsnCode:
      type: integer
      minimum: 1
      description: An autonomous system number (ASN).
    Latitude:
      type: number
      description: The latitude of probe location.
    Longitude:
      type: number
      description: The longitude of probe location.
    Probes:
      type: array
      items:
        $ref: '#/components/schemas/Probe'
    ProbeLocation:
      type: object
      description: The probe location information.
      required:
      - continent
      - region
      - country
      - state
      - city
      - asn
      - network
      - latitude
      - longitude
      properties:
        continent:
          $ref: '#/components/schemas/ContinentCode'
        region:
          $ref: '#/components/schemas/RegionName'
        country:
          $ref: '#/components/schemas/CountryCode'
        state:
          anyOf:
          - $ref: '#/components/schemas/StateCode'
          - type: 'null'
        city:
          $ref: '#/components/schemas/CityName'
        asn:
          $ref: '#/components/schemas/AsnCode'
        network:
          $ref: '#/components/schemas/NetworkName'
        latitude:
          $ref: '#/components/schemas/Latitude'
        longitude:
          $ref: '#/components/schemas/Longitude'
    NetworkName:
      type: string
      description: A network name, such as "Google LLC" or "DigitalOcean, LLC".
    CityName:
      type: string
      description: A city name in English.
    StateCode:
      type: string
      description: A two-letter [US state code](https://www.faa.gov/air_traffic/publications/atpubs/cnt_html/appendix_a.html).
    Probe:
      type: object
      required:
      - version
      - location
      - tags
      - resolvers
      properties:
        version:
          type: string
          description: The probe version.
        location:
          $ref: '#/components/schemas/ProbeLocation'
        tags:
          $ref: '#/components/schemas/Tags'
        resolvers:
          $ref: '#/components/schemas/ProbeResolvers'
    ContinentCode:
      type: string
      description: A two-letter continent code.
      enum:
      - AF
      - AN
      - AS
      - EU
      - NA
      - OC
      - SA
    ProbeResolvers:
      type: array
      description: An array of the default resolvers configured on the probe.
      items:
        $ref: '#/components/schemas/ProbeResolver'
    Tags:
      type: array
      description: 'An array of additional values to fine-tune probe selection:

        - Probes hosted in [AWS](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/using-regions-availability-zones.html#concepts-available-regions), [Google Cloud](https://cloud.google.com/compute/docs/regions-zones#available), [Azure](https://learn.microsoft.com/en-us/azure/reliability/regions-list), and [Oracle Cloud](https://docs.oracle.com/en-us/iaas/Content/General/Concepts/regions.htm) are automatically assigned the service region code. For example: `aws-eu-west-1`, `gcp-us-south1`, `azure-polandcentral`, and `oci-us-ashburn-1`. They are also assigned the provider name: `aws`, `gcp`, `azure`, or `oci`.

        - Probes are automatically assigned `datacenter-network` and `eyeball-network` tags to distinguish between datacenter and end-user locations.

        '
      items:
        type: string
    ProbeResolver:
      anyOf:
      - type: string
        format: ipv4
        description: The IPv4 address of the resolver.
      - type: string
        format: ipv6
        description: 'EXPERIMENTAL: The IPv6 address of the resolver.

          '
      - type: string
        const: private
        description: Indicates that the resolver points to a private IP address.
    CountryCode:
      type: string
      description: A two-letter country code based on [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2#Officially_assigned_code_elements).
  examples:
    probes:
      value:
      - version: 0.20.0
        location:
          continent: NA
          region: Northern America
          country: US
          state: VA
          city: Ashburn
          asn: 14618
          network: Amazon.com, Inc.
          latitude: 39.04
          longitude: -77.49
        tags:
        - aws-us-east-1
        - datacenter-network
        resolvers:
        - private
  responses:
    probes200:
      description: 'A successful request returns status `200 OK` and a body containing a list of all probes currently online and their metadata.

        '
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Probes'
          examples:
            '0':
              $ref: '#/components/examples/probes'
  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.

        '