Documentation

Observiant documentation

Observiant measures latency, packet loss and network paths to the hosts and services you depend on. Measurements come from Observiant's monitoring locations and from agents you run inside your own networks. This documentation explains how the platform is organized and how to automate it with the Observiant API.

Start here

Authentication

Create an API key in the customer portal and make your first authenticated request.

Set up access →Conventions

API overview

Base URL, request and response formats, timestamps, errors and per-endpoint limits.

Read the overview →Reference

Targets

Create, update and remove what Observiant measures, and choose which agents measure it.

Manage targets →

How Observiant is organized

You work with two web addresses:

Address	Used for
https://my.observiant.com	The customer portal: sign-in, your Organization, sub-users, plan and billing, and API keys.
https://<subdomain>.observiant.com	Your environment: the monitoring dashboard and the API for your Organization's data.

Each Organization has one environment. You chose its subdomain when you signed up, and the portal's Environment page shows its full address. All API requests go to your environment's address.

Concepts

Targets

A target is one thing Observiant measures: a host, given as an IP address or hostname, and a check protocol. Observiant supports five checks:

• ICMP: ping round-trip time and packet loss
• TCP: time to open a TCP connection
• TLS: time to complete a TCP connection and TLS handshake
• HTTP(S): time to the first response byte, with a status-code check
• DNS: time to resolve a name

You can give targets an optional category to group them in the dashboard. See Targets for the full model.

Agents

Agents run the measurements. There are two kinds:

• System agents are monitoring locations operated by Observiant. You choose them as part of your plan. They measure public, globally routable addresses only.
• User agents are agents you install on your own servers. Use them to measure from inside your networks, including private addresses.

Every agent has a stable label and a human-readable display name. The API uses labels to identify agents. System agent labels begin with sys-; a user agent's label is the name you gave it.

By default, every agent measures every target. You can restrict a target to specific agents with agent assignments.

Measurements

Each agent measures each of its targets every 15 seconds. The API returns these measurements as time series of average latency, success rate, and minimum and maximum latency, aggregated into one-minute or longer intervals. See Latency and loss.

Traceroutes

For ICMP targets, agents also run MTR traceroutes automatically. How often they run depends on your plan. Each report lists every hop on the path with its packet loss and latency. Observiant adds the hop's reverse DNS name, autonomous system (AS) and country. See Traceroutes.

Path changes

Observiant compares consecutive traceroutes from each agent to each target. It records a path change when one of the following happens:

• The AS path changes.
• The destination stops or starts answering.
• Hop changes coincide with a change in latency or loss at the destination.

See Path changes.

Correlated events

Sometimes packet loss starts at the same hop and continues to the destination on several target and agent paths within a short time. Observiant then reports a correlated event that identifies that hop, which is usually the most direct pointer to where a problem lies. See Correlated events.

Your first API request

Create an API key as described in Authentication, then list your targets. Replace example with your environment's subdomain:

export OBSERVIANT_URL="https://example.observiant.com"
export OBSERVIANT_API_KEY="obs_api_…"   # paste the key from the portal

curl --header "Authorization: Bearer $OBSERVIANT_API_KEY" \
  "$OBSERVIANT_URL/api/targets"

A new environment returns an empty list, []. Continue with Targets to create your first target.

Data retention

Your plan sets how long measurement history and traceroutes are kept, and the two periods can differ. Requests for older data return empty results.