Check AI spend allowance

curl --request POST \
  --url https://ingest.hyperline.co/v1/ai/billing/check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": "acme-corp",
  "agent": "invoice-copilot",
  "action": "deep_research"
}
'

import requests

url = "https://ingest.hyperline.co/v1/ai/billing/check"

payload = {
    "customer": "acme-corp",
    "agent": "invoice-copilot",
    "action": "deep_research"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({customer: 'acme-corp', agent: 'invoice-copilot', action: 'deep_research'})
};

fetch('https://ingest.hyperline.co/v1/ai/billing/check', 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://ingest.hyperline.co/v1/ai/billing/check",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer' => 'acme-corp',
    'agent' => 'invoice-copilot',
    'action' => 'deep_research'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://ingest.hyperline.co/v1/ai/billing/check"

	payload := strings.NewReader("{\n  \"customer\": \"acme-corp\",\n  \"agent\": \"invoice-copilot\",\n  \"action\": \"deep_research\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://ingest.hyperline.co/v1/ai/billing/check")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer\": \"acme-corp\",\n  \"agent\": \"invoice-copilot\",\n  \"action\": \"deep_research\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://ingest.hyperline.co/v1/ai/billing/check")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer\": \"acme-corp\",\n  \"agent\": \"invoice-copilot\",\n  \"action\": \"deep_research\"\n}"

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

{
  "agent": "invoice-copilot",
  "allowed": true,
  "reason": "not_configured",
  "balance": {
    "denomination": "minor_units",
    "wallet": "12500",
    "unsettled": "43.218",
    "available": "12456.782"
  },
  "meters": [
    {
      "key": "5h",
      "included_units": "50000",
      "used_units": "12500",
      "remaining_units": "37500",
      "window_started_at": "2026-08-20T09:14:02.113Z",
      "resets_at": "2026-08-20T14:14:02.113Z"
    }
  ],
  "overage": true
}

{
  "code": "not_configured",
  "message": "This customer has no AI billing policy",
  "balance": {
    "denomination": "minor_units",
    "wallet": "12500",
    "unsettled": "43.218",
    "available": "12456.782"
  },
  "meters": [
    {
      "key": "5h",
      "included_units": "50000",
      "used_units": "12500",
      "remaining_units": "37500",
      "window_started_at": "2026-08-20T09:14:02.113Z",
      "resets_at": "2026-08-20T14:14:02.113Z"
    }
  ],
  "resets_at": "2026-08-20T14:14:02.113Z"
}

{
  "code": "not_configured",
  "message": "This customer has no AI billing policy",
  "balance": {
    "denomination": "minor_units",
    "wallet": "12500",
    "unsettled": "43.218",
    "available": "12456.782"
  },
  "meters": [
    {
      "key": "5h",
      "included_units": "50000",
      "used_units": "12500",
      "remaining_units": "37500",
      "window_started_at": "2026-08-20T09:14:02.113Z",
      "resets_at": "2026-08-20T14:14:02.113Z"
    }
  ],
  "resets_at": "2026-08-20T14:14:02.113Z"
}

{
  "code": "not_configured",
  "message": "This customer has no AI billing policy",
  "balance": {
    "denomination": "minor_units",
    "wallet": "12500",
    "unsettled": "43.218",
    "available": "12456.782"
  },
  "meters": [
    {
      "key": "5h",
      "included_units": "50000",
      "used_units": "12500",
      "remaining_units": "37500",
      "window_started_at": "2026-08-20T09:14:02.113Z",
      "resets_at": "2026-08-20T14:14:02.113Z"
    }
  ],
  "resets_at": "2026-08-20T14:14:02.113Z"
}

{
  "code": "not_configured",
  "message": "This customer has no AI billing policy",
  "balance": {
    "denomination": "minor_units",
    "wallet": "12500",
    "unsettled": "43.218",
    "available": "12456.782"
  },
  "meters": [
    {
      "key": "5h",
      "included_units": "50000",
      "used_units": "12500",
      "remaining_units": "37500",
      "window_started_at": "2026-08-20T09:14:02.113Z",
      "resets_at": "2026-08-20T14:14:02.113Z"
    }
  ],
  "resets_at": "2026-08-20T14:14:02.113Z"
}

POST

billing

check

Check AI spend allowance

curl --request POST \
  --url https://ingest.hyperline.co/v1/ai/billing/check \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "customer": "acme-corp",
  "agent": "invoice-copilot",
  "action": "deep_research"
}
'

import requests

url = "https://ingest.hyperline.co/v1/ai/billing/check"

payload = {
    "customer": "acme-corp",
    "agent": "invoice-copilot",
    "action": "deep_research"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({customer: 'acme-corp', agent: 'invoice-copilot', action: 'deep_research'})
};

fetch('https://ingest.hyperline.co/v1/ai/billing/check', 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://ingest.hyperline.co/v1/ai/billing/check",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'customer' => 'acme-corp',
    'agent' => 'invoice-copilot',
    'action' => 'deep_research'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

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

curl_close($curl);

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

package main

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

func main() {

	url := "https://ingest.hyperline.co/v1/ai/billing/check"

	payload := strings.NewReader("{\n  \"customer\": \"acme-corp\",\n  \"agent\": \"invoice-copilot\",\n  \"action\": \"deep_research\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

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

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

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://ingest.hyperline.co/v1/ai/billing/check")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"customer\": \"acme-corp\",\n  \"agent\": \"invoice-copilot\",\n  \"action\": \"deep_research\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://ingest.hyperline.co/v1/ai/billing/check")

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

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"customer\": \"acme-corp\",\n  \"agent\": \"invoice-copilot\",\n  \"action\": \"deep_research\"\n}"

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

{
  "agent": "invoice-copilot",
  "allowed": true,
  "reason": "not_configured",
  "balance": {
    "denomination": "minor_units",
    "wallet": "12500",
    "unsettled": "43.218",
    "available": "12456.782"
  },
  "meters": [
    {
      "key": "5h",
      "included_units": "50000",
      "used_units": "12500",
      "remaining_units": "37500",
      "window_started_at": "2026-08-20T09:14:02.113Z",
      "resets_at": "2026-08-20T14:14:02.113Z"
    }
  ],
  "overage": true
}

{
  "code": "not_configured",
  "message": "This customer has no AI billing policy",
  "balance": {
    "denomination": "minor_units",
    "wallet": "12500",
    "unsettled": "43.218",
    "available": "12456.782"
  },
  "meters": [
    {
      "key": "5h",
      "included_units": "50000",
      "used_units": "12500",
      "remaining_units": "37500",
      "window_started_at": "2026-08-20T09:14:02.113Z",
      "resets_at": "2026-08-20T14:14:02.113Z"
    }
  ],
  "resets_at": "2026-08-20T14:14:02.113Z"
}

{
  "code": "not_configured",
  "message": "This customer has no AI billing policy",
  "balance": {
    "denomination": "minor_units",
    "wallet": "12500",
    "unsettled": "43.218",
    "available": "12456.782"
  },
  "meters": [
    {
      "key": "5h",
      "included_units": "50000",
      "used_units": "12500",
      "remaining_units": "37500",
      "window_started_at": "2026-08-20T09:14:02.113Z",
      "resets_at": "2026-08-20T14:14:02.113Z"
    }
  ],
  "resets_at": "2026-08-20T14:14:02.113Z"
}

{
  "code": "not_configured",
  "message": "This customer has no AI billing policy",
  "balance": {
    "denomination": "minor_units",
    "wallet": "12500",
    "unsettled": "43.218",
    "available": "12456.782"
  },
  "meters": [
    {
      "key": "5h",
      "included_units": "50000",
      "used_units": "12500",
      "remaining_units": "37500",
      "window_started_at": "2026-08-20T09:14:02.113Z",
      "resets_at": "2026-08-20T14:14:02.113Z"
    }
  ],
  "resets_at": "2026-08-20T14:14:02.113Z"
}

{
  "code": "not_configured",
  "message": "This customer has no AI billing policy",
  "balance": {
    "denomination": "minor_units",
    "wallet": "12500",
    "unsettled": "43.218",
    "available": "12456.782"
  },
  "meters": [
    {
      "key": "5h",
      "included_units": "50000",
      "used_units": "12500",
      "remaining_units": "37500",
      "window_started_at": "2026-08-20T09:14:02.113Z",
      "resets_at": "2026-08-20T14:14:02.113Z"
    }
  ],
  "resets_at": "2026-08-20T14:14:02.113Z"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json

Check payload.

customer

string

required

Customer to bill — the external id your application knows them by, or a Hyperline cus_… id. Resolved exactly the way AI telemetry resolves it.

Required string length: 1 - 255

Example:

"acme-corp"

agent

string

The agent making the call, as run({ agent }) names it. Optional, and absent means the customer's shared pool — which is what every call did before per-agent billing existed. Naming an agent only changes anything once an operator has given that agent a billing policy of its own; until then it resolves to the same shared pool and the response says so with agent: null.

Required string length: 1 - 128

Example:

"invoice-copilot"

action

string

Optional action name. Accepted and reserved for per-action allowances; it does not change the verdict in any mode today.

Required string length: 1 - 128

Example:

"deep_research"

Response

Verdict.

agent

string | null

required

The billing scope that answered: the agent's own slug when it has a policy of its own, and null when the customer's shared pool answered — including when an agent was named but has no policy of its own.

Example:

"invoice-copilot"

allowed

boolean

required

Whether the customer may spend right now.

Example:

true

reason

enum<string> | null

required

Why it said no. Null when allowed.

Available options:

not_configured,

unsupported_mode,

customer_not_found,

wallet_missing,

credit_pot_missing,

blocked,

insufficient_balance,

insufficient_credits,

allowance_exhausted,

windows_not_configured

balance

object

required

What the customer can spend. In wallet mode this is the shadow balance — micro-consumption never touches the wallet ledger directly. In credits mode it is the credit pot itself, read live. In windows mode the three numbers describe the binding window, the one with least room left and therefore the one that will refuse the next call; meters carries every window separately.

Show child attributes

meters

object[] | null

required

Every rolling allowance window, in windows mode. Null in every other mode. allowed is false as soon as any one of them is at or below the policy floor.

Show child attributes

overage

boolean

required

True when this allowed: true is an overage verdict — the scope is past its boundary and the next call will be priced in USD rather than refused. Never a denial of its own: allowed still answers "may I proceed".

Example:

true

⌘I