Metrics

This guide walks you through, step by step, how to retrieve metrics for frontdoors, shares, and environments. It shows the common headers, typical query parameters (time ranges, rollups), practical cURL examples, and example responses.

Assumptions

• The examples assume you have a valid Bearer token. If you need help obtaining a token, see [./auth](Auth Guide).
• Base URL for all API calls is https://gateway.production.netfoundry.io/frontdoor
• Expected headers for all API calls:

- Authorization: Bearer YOUR_ACCESS_TOKEN
- Accept: application/hal+json or application/json

Conventions used in this guide

• All requests use HTTPS and include an Authorization header.
• We use RFC 3339 timestamps and ISO-8601 durations for time ranges when supported (for example, PT15M = last 15 minutes, PT1H = last hour, P1D = last day).
• Sample identifiers (UUIDs) are placeholders. Replace them with your actual IDs.
• Example series are simplified to demonstrate structure.

Frontdoors metrics

This section explains how to retrieve metrics for a specific frontdoor. You will typically use these calls to power dashboards, uptime/traffic views, and alerting summaries.

Typical metrics include request rates, error counts, latency percentiles, and bandwidth. Depending on configuration, you may also see per-status code counts or other derived series.

Get the Frontdoor ID

You need a frontdoorId to query metrics. If you already have it, continue to the next step. Otherwise, list your frontdoors (endpoint not shown here) and pick the relevant ID.

For the examples below, we will use:

• frontdoorId: 3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c

Choose your time window

Most metric endpoints accept parameters like:

• duration: An ISO-8601 duration window relative to "now" (for example, PT15M, PT1H, P1D).

Retrieve metrics

Use this when you need explicit granularity or multiple series in one response.

Request (requests and errors, 1-hour window, 1-minute step):

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c/metrics?duration=PT1H&step=PT1M"

Example response:

{
  "frontdoorId" : "b3d70f1f-03c0-4728-a73d-2432bef8e79b",
  "scope" : "account",
  "id" : "9",
  "period" : "2592000",
  "samples" : [ 
      {
        "rx" : 3821,
        "tx" : 513,
        "timestamp" : "2025-06-23T00:00:00.000+00:00"
      }, {
        "rx" : 3282,
        "tx" : 3053,
        "timestamp" : "2025-06-24T00:00:00.000+00:00"
      }, {
        "rx" : 821,
        "tx" : 302513,
        "timestamp" : "2025-06-25T00:00:00.000+00:00"
      }
  ]
}

Shares metrics

Shares commonly represent published resources or routes. Their metrics help you understand usage, error conditions, and performance characteristics of a specific share.

For the examples below, we will use:

• shareId: 9a1fa8f2-4f9a-4c7b-9e4e-00ec8f4a3b77

Metrics for a Share

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/shares/9a1fa8f2-4f9a-4c7b-9e4e-00ec8f4a3b77/metrics?duration=PT1H"

Example response:

{
  "frontdoorId" : "b3d70f1f-03c0-4728-a73d-2432bef8e79b",
  "shareToken" : "2jhbEYiRii2f",
  "scope" : "account",
  "id" : "9",
  "period" : "2592000",
  "samples" : [ 
      {
        "rx" : 3821,
        "tx" : 513,
        "timestamp" : "2025-06-23T00:00:00.000+00:00"
      }, {
        "rx" : 3282,
        "tx" : 3053,
        "timestamp" : "2025-06-24T00:00:00.000+00:00"
      }, {
        "rx" : 821,
        "tx" : 302513,
        "timestamp" : "2025-06-25T00:00:00.000+00:00"
      }
  ]
}

Environments metrics

Environment-level metrics provide a roll-up across frontdoors or shares that belong to the environment. Use these for organization-level health and capacity insights.

For the examples below, we will use:

• environmentId: 1c8b1e1f6442

Request example

curl -s \
  -H "Authorization: Bearer $TOKEN" \
  -H "Accept: application/json" \
  "https://gateway.production.netfoundry.io/frontdoor/environments/1c8b1e1f6442/metrics?range=PT1H"

Example response:

{
  "frontdoorId" : "b3d70f1f-03c0-4728-a73d-2432bef8e79b",
  "envZId" : "L11iq5z-oHO2jhbEiiYiR",
  "scope" : "account",
  "id" : "9",
  "period" : "2592000",
  "samples" : [ 
      {
        "rx" : 3821,
        "tx" : 513,
        "timestamp" : "2025-06-23T00:00:00.000+00:00"
      }, {
        "rx" : 3282,
        "tx" : 3053,
        "timestamp" : "2025-06-24T00:00:00.000+00:00"
      }, {
        "rx" : 821,
        "tx" : 302513,
        "timestamp" : "2025-06-25T00:00:00.000+00:00"
      }
  ]
}

Quick reference: example endpoints

Replace IDs with your own.

• Frontdoor metrics (last hour):

GET https://gateway.production.netfoundry.io/frontdoor/{frontdoorId}/metrics?range=PT1H

• Share metrics:

GET https://gateway.production.netfoundry.io/frontdoor/shares/{shareId}/metrics?duration=P1D

• Environment metrics:

GET https://gateway.production.netfoundry.io/frontdoor/environments/{environmentId}/metrics?duration=PT1H

All requests should include:

Authorization: Bearer YOUR_ACCESS_TOKEN
Accept: application/json
Content-Type: application/json

Common errors

400 Bad Request (client error)

{
  "error": "invalid_request",
  "message": "Value for <property> must be of <type>"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

401 Unauthorized (missing/expired token)

{
  "error": "unauthorized",
  "message": "Bearer token is missing or invalid"
}

Possible reasons include:

• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.

403 Forbidden (not_authorized)

{
  "error": "not_found",
  "message": "Frontdoor 3d6d2b6e-6c7a-4a7f-8c3d-9a9d2e1f0b1c not found"
}

Possible reasons include:

• Invalid token: The token is not valid.
• The token does not grant access to the requested resource.
• Clock skew: If tokens seem instantly expired, check system time synchronization on the machine making requests.
• Token format: Authorization header must be exactly Authorization: Bearer <token> with a space after Bearer or Authorization: Basic <username:token> with a space after Basic and a color separator.