API Keys

Get Key Usage

Everything the console’s Requests page draws, per key.

Four series, all read from counters that already exist rather than derived from an estimate:

days / month_to_date — the daily counter written by auth._check_rate_limit on the pipeline that already runs for every keyed request. Backs the 30-day view and the monthly quota.
hours — the hourly request and error counters, for the traffic chart and its error strip.
latency — six fixed buckets summed over the same hourly window. Percentiles are bucket UPPER BOUNDS, never interpolated; see :class:LatencySummary.
recent — the per-key ring of the last RECENT_MAX requests, newest first. Route TEMPLATES only, so no request identifiers are retained.

Only the caller’s own keys. The prefixes are read from api_keys filtered by user_id and never from user input, so there is no way to address another tenant’s telemetry by asking for it.

Fails SOFT: a Redis outage yields zeroes and empty lists, not a 500. This is a dashboard panel — a broken chart must not take down the page that also shows someone their API key. A zero here is visibly a zero; it is not presented as a measured absence of traffic.

GET

keys

usage

Get Key Usage

curl --request GET \
  --url https://api.polysimulator.com/v1/keys/usage \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.polysimulator.com/v1/keys/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polysimulator.com/v1/keys/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polysimulator.com/v1/keys/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.polysimulator.com/v1/keys/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

[
  {
    "key_prefix": "<string>",
    "days": [
      {
        "date": "<string>",
        "requests": 123
      }
    ],
    "month_to_date": 123,
    "monthly_request_cap": 123,
    "latency": {
      "samples": 123,
      "p50_ms": 123,
      "p99_ms": 123,
      "buckets": {}
    },
    "hours": [
      {
        "hour": "<string>",
        "requests": 123,
        "errors": 123
      }
    ],
    "recent": [
      {
        "status": 123,
        "method": "<string>",
        "route": "<string>",
        "latency_ms": 123,
        "at": "<string>"
      }
    ]
  }
]

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

Authorizations

X-API-Key

string

header

required

Issue from /v1/keys (or admin-issued for enterprise tier).

Headers

authorization

string | null

X-API-Key

string | null

POLY_API_KEY

string | null

Poly-API-Key

string | null

Query Parameters

days

integer

default:30

hours

integer

default:24

recent

integer

default:50

Response

Successful Response

key_prefix

string

required

days

UsageDay · object[]

required

Show child attributes

month_to_date

integer

required

Sum over the current UTC calendar month

monthly_request_cap

integer

required

Requests this key may make in one UTC calendar month, from its rate-limit tier. Reported so a caller can see the headroom before it matters; NOT enforced yet.

latency

LatencySummary · object

required

Approximate latency over the same window

Show child attributes

hours

UsageHour · object[]

Hourly buckets, oldest first, over the requested hours window

Show child attributes

recent

RecentRequest · object[]

Most recent requests for this key, newest first

Show child attributes

Get Key Usage

curl --request GET \
  --url https://api.polysimulator.com/v1/keys/usage \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

fetch('https://api.polysimulator.com/v1/keys/usage', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.polysimulator.com/v1/keys/usage",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "X-API-Key: <api-key>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.polysimulator.com/v1/keys/usage"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-API-Key", "<api-key>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.polysimulator.com/v1/keys/usage")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-API-Key"] = '<api-key>'

response = http.request(request)
puts response.read_body

[
  {
    "key_prefix": "<string>",
    "days": [
      {
        "date": "<string>",
        "requests": 123
      }
    ],
    "month_to_date": 123,
    "monthly_request_cap": 123,
    "latency": {
      "samples": 123,
      "p50_ms": 123,
      "p99_ms": 123,
      "buckets": {}
    },
    "hours": [
      {
        "hour": "<string>",
        "requests": 123,
        "errors": 123
      }
    ],
    "recent": [
      {
        "status": 123,
        "method": "<string>",
        "route": "<string>",
        "latency_ms": 123,
        "at": "<string>"
      }
    ]
  }
]

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

{
  "error": "<string>",
  "message": "<string>",
  "details": {},
  "request_id": "<string>"
}

Overview

Endpoints

Get Key Usage

Authorizations

Headers

Query Parameters

Response