This documentation covers the various job types available through the Customer Jobs API. Each job type allows you to perform specific network tests from different locations and ISPs.

OpenAPI Documentation

For a comprehensive and interactive view of our API, please refer to our OpenAPI specification:

Bitping API OpenAPI Specification

For the best experience, we recommend viewing the specification in an OpenAPI viewer such as Swagger UI or ReDoc. You can also import the URL into Yaak, Postman, Insomnia or your favourite desktop API client.

DNS Lookup

Perform a DNS lookup for specified hostnames.

Endpoint

POST /jobs/customer/dns

Request Body

Field	Type	Description
hostnames	string[]	Array of hostnames to lookup
countryCode	string (optional)	Filter nodes by country code
ispRegex	string (optional)	Filter nodes by ISP regex
configuration	object (optional)	DNS-specific configuration

Configuration Object

Field	Type	Description
dnsServers	string[] (optional)	List of DNS servers to use (e.g. ‘8.8.8.8:53’, ‘1.1.1.1:53’)
lookupTypes	string[] (optional)	Types of DNS lookups to perform (e.g., “MX”, “NS”, “IP”, “TXT”, “SOA”, “SRV”, “TLSA”)

Response

Returns the DNS lookup results along with node information.

{
  nodeInfo: {
    operatingSystem: string;
    isp: string;
    mobile: boolean;
    proxy: boolean;
    regionName: string;
    countryCode: string;
    lat: number;
    lon: number;
  };
  results: Array<{
    endpoint: string;
    duration: number;
    error?: string;
    result?: {
      mx: string[];
      ns: string[];
      ips: string[];
      txt: string[];
      soa: string[];
      srv: string[];
      tlsa: string[];
      dnsServers: string[];
    };
  }>;
}

HTTP Request

Perform an HTTP request to specified hostnames.

Endpoint

POST /jobs/customer/http/{method}

Parameters

Parameter	Description
method	The HTTP method to use (e.g., GET, POST, PUT, PATCH, DELETE, OPTIONS, HEAD)

Request Body

Field	Type	Description
hostnames	string[]	Array of hostnames to send the request to
countryCode	string (optional)	Filter nodes by country code
ispRegex	string (optional)	Filter nodes by ISP regex
configuration	object (optional)	HTTP-specific configuration

Configuration Object

Field	Type	Description
headers	object (optional)	Key-value pairs of HTTP headers
regex	string (optional)	Regex pattern to match in the response
statusCodes	number[] (optional)	Expected status codes
body	string (optional)	Request body for POST, PUT, PATCH requests
returnBody	boolean (optional)	Whether to return the response body

Response

Returns the HTTP response along with node information.

{
  nodeInfo: {
    operatingSystem: string;
    isp: string;
    mobile: boolean;
    proxy: boolean;
    regionName: string;
    countryCode: string;
    lat: number;
    lon: number;
  };
  results: Array<{
    endpoint: string;
    duration: number;
    error?: string;
    result?: {
      statusCode: number;
      bodyHash: string;
      matches: string[];
      headers: Record<string, string>;
      body?: string;
    };
  }>;
}

ICMP Ping

Perform a ping test to specified hostnames.

Endpoint

POST /jobs/customer/ping/icmp

Request Body

Field	Type	Description
hostnames	string[]	Array of hostnames to ping
countryCode	string (optional)	Filter nodes by country code
ispRegex	string (optional)	Filter nodes by ISP regex
configuration	object (optional)	ICMP-specific configuration

Configuration Object

Field	Type	Description
attempts	number (optional)	Number of ping attempts
payloadSize	number (optional)	Size of the ping payload
timeoutMillis	number (optional)	Timeout in milliseconds

Response

Returns the ping results along with node information.

{
  nodeInfo: {
    operatingSystem: string;
    isp: string;
    mobile: boolean;
    proxy: boolean;
    regionName: string;
    countryCode: string;
    lat: number;
    lon: number;
  };
  results: Array<{
    endpoint: string;
    duration: number;
    error?: string;
    result?: {
      avg: number;
      max: number;
      min: number;
      stdDev: number;
      ipAddress: string;
      packetLoss: number;
      packetsRecv: number;
      packetsSent: number;
      trips: number;
      attempts: number;
    };
  }>;
}

HLS Stream Test

Perform an HLS (HTTP Live Streaming) test on specified stream URLs.

Endpoint

POST /jobs/customer/hls

Request Body

Field	Type	Description
hostnames	string[]	Array of HLS stream URLs to test
countryCode	string (optional)	Filter nodes by country code
ispRegex	string (optional)	Filter nodes by ISP regex
configuration	object (optional)	HLS-specific configuration

Configuration Object

Field	Type	Description
headers	object (optional)	Key-value pairs of HTTP headers

Response

Returns the HLS stream test results along with node information.

{
  nodeInfo: {
    operatingSystem: string;
    isp: string;
    mobile: boolean;
    proxy: boolean;
    regionName: string;
    countryCode: string;
    lat: number;
    lon: number;
  };
  results: Array<{
    endpoint: string;
    duration: number;
    error?: string;
    result?: {
      master: {
        file: string;
        downloadMetrics: {
          size: number;
          timeMs: number;
          bytesPerSecond: number;
        };
        metrics: {
          dnsResolveDurationMs?: number;
          tcpConnectDurationMs: number;
          tlsHandshakeDurationMs?: number;
          httpGetSendDurationMs: number;
          httpTtfbDurationMs: number;
        };
        renditions: Array<{
          file: string;
          downloadMetrics: {
            size: number;
            timeMs: number;
            bytesPerSecond: number;
          };
          metrics: {
            dnsResolveDurationMs?: number;
            tcpConnectDurationMs: number;
            tlsHandshakeDurationMs?: number;
            httpGetSendDurationMs: number;
            httpTtfbDurationMs: number;
          };
          contentFragmentMetrics: Array<{
            file: string;
            contentFragmentDurationSecs: number;
            metrics: {
              dnsResolveDurationMs?: number;
              tcpConnectDurationMs: number;
              tlsHandshakeDurationMs?: number;
              httpGetSendDurationMs: number;
              httpTtfbDurationMs: number;
            };
            downloadMetrics: {
              size: number;
              timeMs: number;
              bytesPerSecond: number;
            };
            downloadRatio: number;
          }>;
          targetDurationSecs: number;
          discontinuitySequence: number;
          resolution: string;
          bandwidth: number;
        }>;
      };
      rendition: {
        file: string;
        downloadMetrics: {
          size: number;
          timeMs: number;
          bytesPerSecond: number;
        };
        metrics: {
          dnsResolveDurationMs?: number;
          tcpConnectDurationMs: number;
          tlsHandshakeDurationMs?: number;
          httpGetSendDurationMs: number;
          httpTtfbDurationMs: number;
        };
        contentFragmentMetrics: Array<{
          file: string;
          contentFragmentDurationSecs: number;
          metrics: {
            dnsResolveDurationMs?: number;
            tcpConnectDurationMs: number;
            tlsHandshakeDurationMs?: number;
            httpGetSendDurationMs: number;
            httpTtfbDurationMs: number;
          };
          downloadMetrics: {
            size: number;
            timeMs: number;
            bytesPerSecond: number;
          };
          downloadRatio: number;
        }>;
        targetDurationSecs: number;
        discontinuitySequence: number;
        resolution: string;
        bandwidth: number;
      };
    };
  }>;
}