Get box usage

GET

boxes

{boxId}

usage

Get box usage

curl --request GET \
  --url https://ascii.dev/api/box/v1/boxes/{boxId}/usage \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://ascii.dev/api/box/v1/boxes/{boxId}/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://ascii.dev/api/box/v1/boxes/{boxId}/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 => [
    "Authorization: Bearer <token>"
  ],
]);

$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://ascii.dev/api/box/v1/boxes/{boxId}/usage"

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

	req.Header.Add("Authorization", "Bearer <token>")

	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://ascii.dev/api/box/v1/boxes/{boxId}/usage")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "ok": true,
  "type": "box.usage",
  "boxId": "bx_23456789",
  "boxType": "default",
  "billingMultiplier": 1,
  "since": "2026-09-01T00:00:00.000Z",
  "until": "2026-09-14T09:30:00.000Z",
  "seconds": 4980,
  "dollars": 0.0498,
  "secondsPerDollar": 100000,
  "running": false
}

{
  "ok": false,
  "type": "box.error",
  "status": 400,
  "code": "invalid_json",
  "message": "Request body must be valid JSON.",
  "error": {
    "code": "invalid_json",
    "message": "Request body must be valid JSON.",
    "status": 400
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "box.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "box.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}

Authorizations

Authorization

string

header

required

Box bearer token in the form box_.... Service API keys authenticate Box operations.

Path Parameters

boxId

string

required

Public Box id returned by create/list/get box calls.

Pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$

Query Parameters

since

string

Count from this time, ISO 8601 or Unix epoch seconds. Default is the box's creation.

until

string

Count up to this time, ISO 8601 or Unix epoch seconds. Default is now.

Response

Billable machine time for the box inside the window.

boolean

required

Example:

true

type

string

required

Stable success envelope discriminator added by v1.

Example:

"box.usage"

boxId

string

required

Pattern: ^bx_[23456789abcdefghjkmnpqrstuvwxyz]{8}$

Example:

"bx_23456789"

boxType

enum<string>

required

The box's current machine size, which sets billingMultiplier.

Available options:

small,

default,

large,

xlarge

billingMultiplier

number

required

Rate at which this box consumes machine time. 0.5 for small, 1 for default, 2 for large, and 50/9 for xlarge.

Example:

1

since

string<date-time>

required

Start of the window the figures cover. The box's creation time when the request did not pass since.

until

string<date-time>

required

End of the window. Now when the request did not pass until, or passed one in the future.

seconds

integer

required

Billable machine-seconds inside the window, the type multiplier already applied: a large box that ran ten minutes reads 1200. Includes a running box's time up to until. Time while stopped is never counted and time past a refused stop is excluded.

Example:

4980

dollars

number

required

seconds at list price (seconds / secondsPerDollar), whatever plan, trial or gift actually paid for it. Up to six decimals.

Example:

0.0498

secondsPerDollar

integer

required

How many billable seconds one dollar buys, so you can price seconds yourself.

Example:

100000

running

boolean

required

The meter is still moving: the box is up and no refused stop is holding it paused. Read again after it stops for the final figure. false on a box that is up but paused past a refused stop, whose figure will not change until it is used again.

Get box usage

curl --request GET \
  --url https://ascii.dev/api/box/v1/boxes/{boxId}/usage \
  --header 'Authorization: Bearer <token>'

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://ascii.dev/api/box/v1/boxes/{boxId}/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://ascii.dev/api/box/v1/boxes/{boxId}/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 => [
    "Authorization: Bearer <token>"
  ],
]);

$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://ascii.dev/api/box/v1/boxes/{boxId}/usage"

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

	req.Header.Add("Authorization", "Bearer <token>")

	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://ascii.dev/api/box/v1/boxes/{boxId}/usage")

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

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

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

{
  "ok": true,
  "type": "box.usage",
  "boxId": "bx_23456789",
  "boxType": "default",
  "billingMultiplier": 1,
  "since": "2026-09-01T00:00:00.000Z",
  "until": "2026-09-14T09:30:00.000Z",
  "seconds": 4980,
  "dollars": 0.0498,
  "secondsPerDollar": 100000,
  "running": false
}

{
  "ok": false,
  "type": "box.error",
  "status": 400,
  "code": "invalid_json",
  "message": "Request body must be valid JSON.",
  "error": {
    "code": "invalid_json",
    "message": "Request body must be valid JSON.",
    "status": 400
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "box.error",
  "status": 401,
  "code": "unauthorized",
  "message": "Unauthorized",
  "error": {
    "code": "unauthorized",
    "message": "Unauthorized",
    "status": 401
  },
  "requestId": "req_01HX..."
}

{
  "ok": false,
  "type": "box.error",
  "status": 409,
  "code": "provider_not_configured",
  "message": "Prompting is locked until Codex is configured on the Agents page.",
  "requestId": "req_01HX...",
  "error": {
    "code": "<string>",
    "message": "<string>",
    "status": 123,
    "details": {}
  }
}