API overview

The Observiant API is a JSON-over-HTTPS API served by your environment. Use it to manage targets from your inventory or automation tooling, and to pull measurements, traceroutes and events into your own systems.

Base URL

Send requests to your environment's address. All endpoints are under /api:

https://<subdomain>.observiant.com/api

The portal's Environment page shows your environment's address. The API is available over HTTPS only. Every request needs an API key, as described in Authentication.

Endpoints

These endpoints are available to API keys. Requests to any other path or method return 403 Forbidden.

Method	Path	Purpose
GET	/api/targets	List targets
POST	/api/targets	Create a target
GET	/api/targets/{target_id}	Get a target
PUT	/api/targets/{target_id}	Replace a target
DELETE	/api/targets/{target_id}	Delete a target and its data
GET	/api/targets/{target_id}/agents	List agent assignments
PUT	/api/targets/{target_id}/agents/{agent_label}	Assign an agent
DELETE	/api/targets/{target_id}/agents/{agent_label}	Remove an assignment
GET	/api/targets/{target_id}/ipinfo	Resolve a target's address, network and country
GET	/api/targets/{target_id}/data/latency	Latency and loss time series
GET	/api/targets/{target_id}/mtr	List traceroute summaries
GET	/api/targets/{target_id}/mtr/markers	Representative traceroutes for a time window
GET	/api/targets/{target_id}/mtr/nearest	Traceroute closest to a point in time
GET	/api/mtr/{result_id}	Get a full traceroute report
GET	/api/targets/{target_id}/path-changes	Route changes
GET	/api/events/mtr	Correlated packet-loss events

Requests

• Send request bodies as JSON with Content-Type: application/json. A body must contain exactly one JSON object of at most 64 KiB.
• Unknown fields are rejected with 400 Bad Request, so a misspelled field name fails instead of being silently ignored.
• Query parameters are optional unless an endpoint says otherwise.
• URL-encode path segments. Agent labels can contain spaces, which you send as %20.

Responses

Responses are JSON. Successful requests return:

Status	Returned by
200 OK	Reads, and target creation, which returns the new target.
204 No Content	Target updates, deletions, and agent assignment changes. There is no body.

Fields that do not apply to a resource can be absent. For example, HTTP-specific fields appear only on HTTP targets. Ignore fields you do not recognize, because new fields can be added to responses.

Identifiers

Targets and traceroute reports have server-assigned IDs (target_id and result_id). IDs are 26-character strings made of letters and digits, such as 01M4MZ5T3A76E4RBFKGBD5MP8V. Treat them as opaque, case-sensitive values.

Timestamps

Every timestamp, in requests and responses, is a Unix time in milliseconds, UTC. Time ranges given with start and end include both ends.

date +%s000                           # now
echo $(( $(date +%s) - 3600 ))000     # one hour ago

import time

now_ms = int(time.time() * 1000)
one_hour_ago_ms = now_ms - 3600 * 1000

Agent labels and display names

Responses that come from agents carry two names:

• agent_label is the agent's stable identifier. Use it in filters such as agent_label=sys-amsterdam and in agent assignments.
• display_name is the human-readable name shown in the dashboard. Use it for presentation only, because it can change. When an agent has no separate display name, display_name equals the label.

System agent labels begin with sys-. A user agent's label is the name you gave it when you added it in the dashboard.

To find system agent labels, read any measurement response. For example, every series returned by latency and loss includes both agent_label and display_name.

Errors

Errors come from two layers, which you can tell apart by the response body.

Authorization errors are returned before the request reaches your environment. They have an empty body:

Status	Meaning
401 Unauthorized	Missing, malformed or revoked API key, or a key from another Organization.
403 Forbidden	The endpoint or method is not available to API keys.
404 Not Found	The address is not an active Observiant environment.
503 Service Unavailable	Authorization is temporarily unavailable. Retry with backoff.

API errors have a JSON body with an error message:

{"error": "family must be auto, ipv4 or ipv6"}

Status	Meaning
400 Bad Request	A parameter or field is invalid, missing or unknown. The message names the problem.
403 Forbidden	Your plan's target limit is reached (target creation only).
404 Not Found	The target, traceroute report or assignment does not exist, or there is no data to return.
500 Internal Server Error	The request failed in Observiant. Retry with backoff.
502 Bad Gateway	A target's hostname could not be resolved (address lookups only).

Error messages are written for people and can change. Base your automation on status codes, and log the message for troubleshooting.

Limits and pagination

List endpoints cap the number of results per request:

Endpoint	Order	Default	Maximum	Time range
GET /api/targets	Label	All targets	All targets	—
GET …/data/latency	Time, oldest first	—	—	Default last 24 hours; any length
GET …/mtr	Time, newest first	50	500	Unbounded by default; up to 30 days when both ends are given
GET …/mtr/markers	Time, oldest first	300	500	start and end required; up to 366 days
GET …/path-changes	Time, oldest first	500	500	Unbounded by default; up to 30 days when both ends are given
GET /api/events/mtr	Most recently seen first	100 per page	500 per page	Default last 24 hours; up to 30 days

Traceroute and path-change lists use time-based paging: to fetch the next set, repeat the request with a range that starts or ends just past the last item you received. Each reference page explains the exact steps. Correlated events use page numbers.

Measurements change every 15 seconds and traceroutes less often, so polling more often than once a minute returns little new data.

Data retention

Your plan sets how long Observiant keeps latency measurements and traceroutes. Path changes and correlated events are kept for as long as traceroutes. Requests for older data return empty results.