Professional API

TraceLog API

Integrate TraceLog real data into your own systems, dashboards and automations via our secure RESTful API.

Authentication

All requests must include your API key in the Authorization header as a Bearer token. For security, our keys are stored with SHA-256 hash and can be rotated at any time.

Authorization: Bearer YOUR_API_KEY

Team Scoping

The API only returns resources linked to your current Team. If you are part of multiple teams, data will be filtered by the team selected at the time of key generation.

Manage keys in API Settings.

Base URL

https://tracelog.evocode.ia.br/api/v1

Our API follows REST standards and uses JSON for all data communications.

Available Endpoints

GET/sensors

Lists all probes linked to your current team. Allows identifying the connectivity status and the last synchronization of each agent. Note: earlier versions of this documentation advertised a `visible_api_key` field that this endpoint never actually populated (it always returned `null`) and that stopped appearing in the response as of 2026-08. To reveal a probe's key, use the Probes screen in the dashboard.

Request Examples

List Probes

curl -X GET "https://tracelog.evocode.ia.br/api/v1/sensors" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Response Example

[
  {
    "id": 1,
    "name": "São Paulo DataCenter",
    "status": "online",
    "city": "São Paulo",
    "country_code": "BR",
    "last_checkin_at": "2024-01-16T15:00:00Z"
  },
  {
    "id": 2,
    "name": "US-East Lambda Probe",
    "status": "offline",
    "city": "Ashburn",
    "country_code": "US",
    "last_checkin_at": "2024-01-15T10:22:00Z"
  }
]

GET/targets

Returns the list of monitoring targets (destinations) registered in your account.

Request Examples

List Targets

curl -X GET "https://tracelog.evocode.ia.br/api/v1/targets" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

[
  {
    "id": 101,
    "name": "Gateway Principal",
    "host": "200.150.10.1",
    "status": "stable",
    "frequency": 5,
    "tags": [
      "infra",
      "core"
    ],
    "health_check_settings": [
      {
        "key": "dns_resolve",
        "type": "dns_resolve",
        "enabled": true,
        "timeout_ms": 3000
      }
    ]
  },
  {
    "id": 102,
    "name": "Google DNS",
    "host": "8.8.8.8",
    "status": "warning",
    "frequency": 1,
    "tags": [
      "external"
    ],
    "trigger_settings": {
      "monitor_performance_degradation": true,
      "latency_threshold_ms": 50,
      "loss_threshold_percentage": 10,
      "condition_duration_minutes": 5,
      "max_hops": 20
    },
    "monitor_load_balancing": true
  }
]

POST/sensor/report-health

Sensor-only endpoint for real protocol health checks. Probes can report TCP connect, HTTP status, TLS handshake, DNS resolve, UDP and ICMP/MTR health results. These checks create technical observations and feed target health scores before an event is promoted to an incident.

Request Examples

Report HTTPS health

curl -X POST "https://tracelog.evocode.ia.br/api/v1/sensor/report-health" \
  -H "X-Sensor-Key: SENSOR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"target_id":101,"check_type":"http_status","protocol":"ipv4","transport_protocol":"tcp","status":"up","success":true,"duration_ms":58,"status_code":200}'

Response Example

{
  "status": "ok",
  "id": 9001
}

GET/events

Access the history of events and route anomalies. There are 6 types in 3 families — availability: target_offline and target_online (per probe and protocol); quality: performance_degradation (the single quality event; details.metric is latency, loss or both, and status moves through suspected → confirmed → recovered); path: route_change (with old_hop_count, new_hop_count, hop_count_delta and, when severity is raised to warning, correlated_event_id), final_host_change and routing_loop. Historical rows may still carry the retired types high_latency, packet_loss, hop_count_exceeded and load_balancing; load balancing and hop count are now observations, not events. Details include status, confidence and evidence to tell confirmed incidents from suspected or observed behaviour. By default the response is paginated by page number, with `total` and `last_page` — use that mode to locate or jump to a specific page. To walk a long history or export data, use `?paginate=cursor` (or pass `?cursor=`): the envelope switches to cursor, with constant cost at any query depth, but without `total` or `last_page` — computing the total would require counting the whole table on every request.

Request Examples

Events from the last 24h

curl -X GET "https://tracelog.evocode.ia.br/api/v1/events?hours=24" \
  -H "Authorization: Bearer YOUR_API_KEY"

Filter by Target

curl -X GET "https://tracelog.evocode.ia.br/api/v1/events?target_id=101" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cursor pagination (long history)

curl -X GET "https://tracelog.evocode.ia.br/api/v1/events?hours=24&paginate=cursor" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

Numbered page (default)

{
  "current_page": 1,
  "data": [
    {
      "id": 5002,
      "type": "route_change",
      "target_id": 101,
      "sensor_id": 1,
      "details_json": {
        "old_hop_count": 12,
        "new_hop_count": 14,
        "hop_count_delta": 2,
        "correlated_event_id": 5003,
        "correlated_event_type": "performance_degradation",
        "status": "confirmed",
        "confidence": 82,
        "evidence": [
          {
            "source": "route_diff",
            "label": "Comparação de rota anterior e atual",
            "observed": {
              "diff_type": "asn_path_change"
            }
          }
        ]
      },
      "created_at": "2024-01-16T14:30:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "stable"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    },
    {
      "id": 5003,
      "type": "performance_degradation",
      "target_id": 101,
      "sensor_id": 1,
      "details_json": {
        "metric": "latency",
        "latency": 150.5,
        "loss": 0,
        "thresholds": {
          "latency": 100,
          "loss": 10
        },
        "duration": 5,
        "protocol": "ipv4",
        "status": "confirmed",
        "affected_hops": [
          7,
          8
        ],
        "confidence": 88,
        "evidence": [
          {
            "source": "sample_metrics",
            "label": "Latência acima do limiar durante toda a janela"
          }
        ]
      },
      "created_at": "2024-01-16T14:35:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "stable"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    },
    {
      "id": 5004,
      "type": "target_offline",
      "target_id": 101,
      "sensor_id": 1,
      "details_json": {
        "loss_percentage": 100,
        "protocol": "ipv4",
        "consecutive_count": 3,
        "status": "confirmed",
        "confidence": 95,
        "evidence": [
          {
            "source": "sample_metrics",
            "label": "Perda de 100% em 3 amostras consecutivas"
          }
        ]
      },
      "created_at": "2024-01-16T14:40:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "offline"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    }
  ],
  "total": 1250,
  "per_page": 50
}

Cursor (paginate=cursor)

{
  "data": [
    {
      "id": 5002,
      "type": "route_change",
      "target_id": 101,
      "sensor_id": 1,
      "details_json": {
        "old_hop_count": 12,
        "new_hop_count": 14,
        "hop_count_delta": 2,
        "correlated_event_id": 5003,
        "correlated_event_type": "performance_degradation",
        "status": "confirmed",
        "confidence": 82
      },
      "created_at": "2024-01-16T14:30:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "stable"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    }
  ],
  "path": "https://tracelog.evocode.ia.br/api/v1/events",
  "per_page": 50,
  "next_cursor": "eyJpZCI6NTAwMiwiY3JlYXRlZF9hdCI6IjIwMjQtMDEtMTZUMTQ6MzA6MDBaIn0",
  "next_page_url": "https://tracelog.evocode.ia.br/api/v1/events?cursor=eyJpZCI6NTAwMiwiY3JlYXRlZF9hdCI6IjIwMjQtMDEtMTZUMTQ6MzA6MDBaIn0",
  "prev_cursor": null,
  "prev_page_url": null
}

GET/latency

High-frequency endpoint to get raw performance data (latency, jitter and loss). By default the response is paginated by numbered page, with `total` and `last_page` — use this mode to locate a specific page. To page through long history or export data, use `?paginate=cursor` (or pass `?cursor=`): measured with 2,000,000 rows and batches of 50, the per-page cost grows from ~111 ms on the first batch to ~1437 ms on the last, while the cursor stays at ~25 ms at any depth — because this envelope has no `total`/`last_page`, which would require counting the whole table on every request.

Request Examples

Recent Performance

curl -X GET "https://tracelog.evocode.ia.br/api/v1/latency?hours=1&per_page=10" \
  -H "Authorization: Bearer YOUR_API_KEY"

Cursor pagination (long history)

curl -X GET "https://tracelog.evocode.ia.br/api/v1/latency?hours=24&paginate=cursor" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

Numbered page (default)

{
  "current_page": 1,
  "data": [
    {
      "id": 100450,
      "target_id": 101,
      "sensor_id": 1,
      "avg_latency": 12.45,
      "jitter": 1.2,
      "loss_percentage": 0,
      "created_at": "2024-01-16T15:05:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "stable"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    }
  ],
  "total": 450000,
  "per_page": 10
}

Cursor (paginate=cursor)

{
  "data": [
    {
      "id": 100450,
      "target_id": 101,
      "sensor_id": 1,
      "avg_latency": 12.45,
      "jitter": 1.2,
      "loss_percentage": 0,
      "created_at": "2024-01-16T15:05:00Z",
      "target": {
        "id": 101,
        "name": "Gateway Principal",
        "host": "200.150.10.1",
        "status": "stable"
      },
      "sensor": {
        "id": 1,
        "name": "São Paulo DataCenter",
        "status": "online"
      }
    }
  ],
  "path": "https://tracelog.evocode.ia.br/api/v1/latency",
  "per_page": 10,
  "next_cursor": "eyJpZCI6MTAwNDUwLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNlQxNTowNTowMFoifQ",
  "next_page_url": "https://tracelog.evocode.ia.br/api/v1/latency?cursor=eyJpZCI6MTAwNDUwLCJjcmVhdGVkX2F0IjoiMjAyNC0wMS0xNlQxNTowNTowMFoifQ",
  "prev_cursor": null,
  "prev_page_url": null
}

GET/latency-history

Retrieve historical latency metrics for a specific target within a defined time window. Ideal for detailed analysis of past events.

Request Examples

Get History for Window

curl -X GET "https://tracelog.evocode.ia.br/api/v1/latency-history?target_id=101&from=2024-01-16T12:00:00Z&to=2024-01-16T18:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY"

Response Example

[
  {
    "id": 100451,
    "target_id": 101,
    "sensor_id": 1,
    "avg_latency": 12.5,
    "jitter": 1.1,
    "loss_percentage": 0,
    "created_at": "2024-01-16T12:01:00Z"
  },
  {
    "id": 100452,
    "target_id": 101,
    "sensor_id": 1,
    "avg_latency": 12.8,
    "jitter": 1.3,
    "loss_percentage": 0,
    "created_at": "2024-01-16T12:02:00Z"
  }
]

Query Parameters

Parameter	Description	Default
target_id	Unique ID of the target to filter the results.	-
sensor_id	Unique ID of the probe to filter the results.	-
hours	Number of hours back for search.	24
days	Number of days back for search.	-
per_page	Amount of records per page.	50
paginate	Use `cursor` to switch the numbered-page envelope to the cursor (keyset) envelope on /events and /latency.	-
cursor	Cursor value returned in `next_cursor`/`prev_cursor`. Passing it also enables cursor pagination on /events and /latency.	-
from	Start date (ISO 8601) for history range.	-
to	End date (ISO 8601) for history range.	-

Pro Tip

Complement your integrations by cross-referencing event and latency data. Use the IDs obtained from the /targets and /sensors endpoints to create granular filters in your queries.