Tenants

Tenants are a core part of Unblind, the very reason Unblind exists is so you can have observability over your tenants. On this page, we'll dive into the different tenant endpoints you can use to manage tenants and query their telemetry using Unblind API. We'll look at how to query, list, get or update tenants.

The tenant model

The tenant model contains all the metadata about a tenant. Tenant data is derived from the tenant ID attributes sent to Unblind.

Properties

Name
id
Type
string
Description
Unique identifier for the tenant.
Name
name
Type
string
Description
The name for the tenant.

GET/v1/tenants

List all tenants

This endpoint allows you to retrieve a paginated list of all your active tenants. By default, a maximum of a hundred tenants are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of tenants returned.

Request

GET

/v1/tenants

curl https://api.unblind.dev/v1/tenants \
  -X 'GET' \
  -H "Authorization: Bearer <API_KEY>" \
  -d limit=100

Response

{
  "nextPage": null,
  "data": [
    {
      "id": "WAz8eIbvDR60rouK",
      "name": "Acme, Inc.",
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}

GET/v1/tenants/:id

Retrieve a tenant

This endpoint allows you to retrieve a tenant by providing their id. Refer to the list at the top of this page to see which properties are included with tenant objects.

Request

GET

/v1/tenants/WAz8eIbvDR60rouK

curl https://api.unblind.dev/v1/tenants/WAz8eIbvDR60rouK \
  -X 'GET' \
  -H "Authorization: Bearer <API_KEY>"

Response

{
  "id": "WAz8eIbvDR60rouK",
  "name": "Acme, Inc."
}

PUT/v1/tenants/:id

Update a tenant

This endpoint allows you to perform an update on a tenant. Currently, the only attribute that can be updated on tenants is the name attribute which controls how a tenant appears or gets searched in Unblind.

Optional attributes

Name
name
Type
string
Description
The tenant name. By default, this is empty.

Request

PUT

/v1/tenants/WAz8eIbvDR60rouK

curl https://api.unblind.dev/v1/tenants/WAz8eIbvDR60rouK \
  -X 'PUT' \
  -H "Authorization: Bearer <API_KEY>" \
  -d name="Acme, Inc."

Response

{
  "id": "WAz8eIbvDR60rouK",
  "name": "Acme, Inc."
}

POST/v1/tenants/:tenant_id/timeseries

Query timeseries

This endpoint allows you to query a tenant's metric timeseries

Required query parameters

Name
queries
Type
object
Description
Queries object. Fields map one to one metric tag to a value.
Name
startTime
Type
number
Description
Unix timestamp (in seconds).
Name
endTime
Type
number
Description
Unix timestamps (in seconds).

Optional query parameters

Name
interval
Type
number
Description
Intervals of time expressed in seconds.

Request

POST

/v1/tenants/WAz8eIbvDR60rouK/timeseries

curl "https://api.unblind.dev/v1/tenants/WAz8eIbvDR60rouK/timeseries" \
  -X POST \
  -H "Authorization: Bearer <API_KEY>" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      {
        "metrics": [
          "nodejs.eventloop.delay.p50",
          "nodejs.eventloop.delay.p99"
        ],
        "groupBy": ["service.name"],
        "operator": "max",
        "attributes": { "host": ["web01"] }
      }
    ],
    "startTime": 1737168000000,
    "endTime": 1737772799000
  }'

Response

{
  "metadata": [],
  "query" :{},
  "series": [
    {
      "name": "nodejs.eventloop.delay.p50",
      "suggested_label": "NodeJS Event Loop Delay P50",
      "unit": {
        "name": "Milliseconds",
        "short_name": "ms"
      },
      "length": 3,
      "values": [
        10,
        20,
        30
      ]
    }
  ],
  "times": [1763657608, 1763657608, 1763657608]
}

POST/v1/tenants/:tenant_id/logs

Query logs

This endpoint allows you to query a tenant's logs. Response field timestamp is returned as a Unix timestamp in milliseconds.

Required query parameters

Name
startTime
Type
number
Description
Unix timestamp (in seconds).
Name
endTime
Type
number
Description
Unix timestamps (in seconds).

Optional query parameters

Name
body
Type
string | [string]
Description
Body text filter. Supports wildcard patterns like %error%.
Name
traceId
Type
string | [string]
Description
Filter by one or many trace IDs.
Name
spanId
Type
string | [string]
Description
Filter by one or many span IDs.
Name
logId
Type
string | [string]
Description
Filter by one or many log IDs.
Name
severity
Type
string | [string]
Description
Severity filter. Allowed values: TRACE, DEBUG, INFO, WARN, ERROR, FATAL, UNSPECIFIED.
Name
attributes
Type
object
Description
Attributes object, for example { "service.name": "checkout-service" }.
Name
includeAttributes
Type
boolean
Description
Include merged resource/log/scope attributes in each returned log.
Name
pagination
Type
object
Description
Cursor pagination object with limit and page.

Request

POST

/v1/tenants/WAz8eIbvDR60rouK/logs

curl "https://api.unblind.dev/v1/tenants/WAz8eIbvDR60rouK/logs" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
      "startTime": 1737168000,
      "endTime": 1737772799,
      "body": "%request%",
      "severity": ["INFO", "WARN"],
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "spanId": "00f067aa0ba902b7",
      "attributes": {
        "service.name": "checkout-service",
        "http.method": "POST"
      },
      "includeAttributes": true,
      "pagination": {
        "limit": 100
      }
    }'

Response

{
  "nextPage": "eyJ0aW1lc3RhbXAiOjE3Mzc3NzI3OTkxMjMsImxvZ19pZCI6IjEyYzY4MjVlLWI2M2YtNDU0MC04NWI3LTk4M2YxZTUwODQxNCJ9",
  "data": [
    {
      "timestamp": 1737772799123,
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "spanId": "00f067aa0ba902b7",
      "severity": "INFO",
      "serviceName": "checkout-service",
      "body": "Request completed",
      "logId": "12c6825e-b63f-4540-85b7-983f1e508414",
      "attributes": {
        "service.name": "checkout-service",
        "http.method": "POST"
      }
    }
  ]
}

POST/v1/tenants/:tenant_id/traces

Query traces

This endpoint allows you to query a tenant's traces. Response field timestamp is returned as a Unix timestamp in milliseconds.

Required query parameters

Name
startTime
Type
number
Description
Unix timestamp (in seconds).
Name
endTime
Type
number
Description
Unix timestamp (in seconds).

Optional query parameters

Name
traceId
Type
string | [string]
Description
Filter by one or many trace IDs.
Name
spanId
Type
string | [string]
Description
Filter by one or many span IDs.
Name
parentSpanId
Type
string | [string]
Description
Filter by direct parent span ID.
Name
spanName
Type
string | [string]
Description
Filter by span name. Supports wildcard patterns like %checkout%.
Name
spanKind
Type
string | [string]
Description
Span kind filter. Allowed values: SERVER, CLIENT, INTERNAL, PRODUCER, CONSUMER.
Name
statusCode
Type
string | [string]
Description
Status code filter. Allowed values: OK, ERROR, UNSET.
Name
durationMin
Type
number
Description
Minimum span duration in nanoseconds (inclusive).
Name
durationMax
Type
number
Description
Maximum span duration in nanoseconds (inclusive).
Name
attributes
Type
object
Description
Attributes object (resource/span attributes), for example { "service.name": "checkout-service" }.
Name
includeAttributes
Type
boolean
Description
Include attributes in each returned span.
Name
pagination
Type
object
Description
Cursor pagination object with limit and page.

Request

POST

/v1/tenants/WAz8eIbvDR60rouK/traces

curl "https://api.unblind.dev/v1/tenants/WAz8eIbvDR60rouK/traces" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
      "startTime": 1737168000,
      "endTime": 1737772799,
      "spanName": "%checkout%",
      "spanKind": "SERVER",
      "statusCode": ["OK", "ERROR"],
      "durationMin": 10000000,
      "durationMax": 1000000000,
      "attributes": {
        "service.name": "checkout-service",
        "http.method": "POST"
      },
      "includeAttributes": true,
      "pagination": {
        "limit": 100
      }
    }'

Response

{
  "nextPage": "eyJ0aW1lc3RhbXAiOjE3Mzc3NzI3OTkxMjMsInNwYW5faWQiOiI0YmY5MmYzNTc3YjM0ZGE2In0=",
  "data": [
    {
      "timestamp": 1737772799123,
      "traceId": "4bf92f3577b34da6a3ce929d0e0e4736",
      "spanId": "00f067aa0ba902b7",
      "parentSpanId": "b9c7c989f97918e1",
      "spanName": "POST /checkout",
      "spanKind": "SERVER",
      "serviceName": "checkout-service",
      "duration": 50000000,
      "statusCode": "OK",
      "statusMessage": null,
      "attributes": {
        "service.name": "checkout-service",
        "http.method": "POST"
      }
    }
  ]
}

POST/v1/tenants/:tenant_id/usage

Query usage

This endpoint allows you to query a tenant's telemetry usage

Required query parameters

Name
startTime
Type
number
Description
Unix timestamp (in seconds).
Name
endTime
Type
number
Description
Unix timestamps (in seconds).
Name
interval
Type
string
Description
Interval period. Allowed values: day, month.

Request

POST

/v1/tenants/WAz8eIbvDR60rouK/usage

curl "https://api.unblind.dev/v1/tenants/WAz8eIbvDR60rouK/usage" \
  -X POST \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer <API_KEY>" \
  -d '{
      "startTime": 1767222000,
      "endTime": 1769900400
    }'

Response

{
  "logs": {
    "bytes": 854237,
    "units": 4712
  },
  "metrics": {
    "units": 22158
  }
}