> ## Documentation Index
> Fetch the complete documentation index at: https://docs.corsair.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Globalping API reference

> API reference for the Globalping plugin in Corsair: every `globalping.api.*` operation with its input and output types, taken from the plugin's Zod schemas.

> [!NOTE]
>
> **New to Corsair?** See [API access](https://docs.corsair.dev/concepts/api.md), [authentication](https://docs.corsair.dev/concepts/auth.md), and [error handling](https://docs.corsair.dev/concepts/error-handling).

## Health

### get

`health.get`

Read the Globalping health check.

**Risk:** `read`

```ts theme={null}
await corsair.globalping.api.health.get({});
```

**Input:** *empty object*

GET /health. Stores the text body.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `health` | `object` | Yes | — |

> [accordion] health full type
>
> ```ts theme={null}
> {
>   id: string,
>   status: string
> }
> ```

***

## Limits

### get

`limits.get`

Read the current measurement rate limit.

**Risk:** `read`

```ts theme={null}
await corsair.globalping.api.limits.get({});
```

**Input:** *empty object*

GET /v1/limits. Stores the measurements.create bucket.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `limit` | `object` | Yes | — |

> [accordion] limit full type
>
> ```ts theme={null}
> {
>   id: string,
>   type?: string,
>   limit?: number,
>   remaining?: number,
>   reset?: number
> }
> ```

***

## Measurements

### create

`measurements.create`

Start a ping, traceroute, dns, mtr or http test from Globalping probes, picked by location. Uses the hourly measurement allowance, then account credits.

**Risk:** `write`

```ts theme={null}
await corsair.globalping.api.measurements.create({ type: 'ping', target: 'example.com', locations: [{ magic: 'Germany', limit: 2 }], measurementOptions: { packets: 3 } });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `type` | `ping \| traceroute \| dns \| mtr \| http` | Yes | — |
| `target` | `string` | Yes | — |
| `locations` | `object[] \| string` | No | — |
| `limit` | `number` | No | — |
| `timeout` | `number` | No | — |
| `measurementOptions` | `object` | No | — |

POST /v1/measurements. locations takes filters such as \{ magic: 'Germany', limit: 2 } or \{ country: 'US' }, or the id of an earlier measurement to reuse its probes. measurementOptions holds the options for the chosen type (packets, protocol, port, query, resolver, request). The test runs in the background: read it with measurements.get. Stores id, probesCount, and type.

> [accordion] locations full type
>
> ```ts theme={null}
> {
>   magic?: string,
>   continent?: string,
>   region?: string,
>   country?: string,
>   state?: string,
>   city?: string,
>   asn?: number,
>   network?: string,
>   tags?: string[],
>   limit?: number
> }[] | string
> ```

> [accordion] measurementOptions full type
>
> ```ts theme={null}
> {
>   packets?: number,
>   protocol?: ICMP | TCP | UDP | HTTP | HTTPS | HTTP2,
>   port?: number,
>   ipVersion?: 4 | 6,
>   query?: {
>     type: string
>   },
>   resolver?: string,
>   trace?: boolean,
>   request?: {
>     host?: string,
>     path?: string,
>     query?: string,
>     method?: HEAD | GET | OPTIONS,
>     headers?: Record<string, string>
>   }
> }
> ```

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `measurement` | `object` | Yes | — |
| `target` | `string` | No | — |
| `createdAt` | `string` | No | — |
| `updatedAt` | `string` | No | — |
| `results` | `object[]` | No | — |

> [accordion] measurement full type
>
> ```ts theme={null}
> {
>   id: string,
>   probesCount?: number,
>   type?: string,
>   status?: string
> }
> ```

> [accordion] results full type
>
> ```ts theme={null}
> {
>   probe: {
>     continent?: string,
>     region?: string,
>     country?: string,
>     state?: string | null,
>     city?: string,
>     asn?: number,
>     network?: string,
>     latitude?: number,
>     longitude?: number,
>     tags?: string[]
>   },
>   result: {
>     status: string,
>     rawOutput?: string | null,
>     resolvedAddress?: string | null,
>     resolvedHostname?: string | null,
>     statusCode?: number,
>     statusCodeName?: string,
>     stats?: Record<string, number | null>
>   }
> }[]
> ```

***

### get

`measurements.get`

Read a measurement by id with each probe's result. Poll until status is finished. Results are not stored.

**Risk:** `read`

```ts theme={null}
await corsair.globalping.api.measurements.get({ id: 'example' });
```

**Input**

| Name | Type | Required | Description |
| - | - | - | - |
| `id` | `string` | Yes | — |

GET /v1/measurements/\{id}. Returns one result per probe (probe location plus status, rawOutput, resolvedAddress, stats and the type's timings, hops or answers). While status is in-progress, wait at least 500 ms and read again. Stores id, type, status, and probesCount; results are returned but not stored.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `measurement` | `object` | Yes | — |
| `target` | `string` | No | — |
| `createdAt` | `string` | No | — |
| `updatedAt` | `string` | No | — |
| `results` | `object[]` | No | — |

> [accordion] measurement full type
>
> ```ts theme={null}
> {
>   id: string,
>   probesCount?: number,
>   type?: string,
>   status?: string
> }
> ```

> [accordion] results full type
>
> ```ts theme={null}
> {
>   probe: {
>     continent?: string,
>     region?: string,
>     country?: string,
>     state?: string | null,
>     city?: string,
>     asn?: number,
>     network?: string,
>     latitude?: number,
>     longitude?: number,
>     tags?: string[]
>   },
>   result: {
>     status: string,
>     rawOutput?: string | null,
>     resolvedAddress?: string | null,
>     resolvedHostname?: string | null,
>     statusCode?: number,
>     statusCodeName?: string,
>     stats?: Record<string, number | null>
>   }
> }[]
> ```

***

## Probes

### list

`probes.list`

List online Globalping probes. Probe rows are not stored.

**Risk:** `read`

```ts theme={null}
await corsair.globalping.api.probes.list({});
```

**Input:** *empty object*

GET /v1/probes. Resolver addresses are not returned.

**Output**

| Name | Type | Required | Description |
| - | - | - | - |
| `probes` | `object[]` | Yes | — |

> [accordion] probes full type
>
> ```ts theme={null}
> {
>   version?: string,
>   continent?: string,
>   region?: string,
>   country?: string,
>   city?: string,
>   network?: string,
>   asn?: number
> }[]
> ```

***


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.