Home › Usage Query

Usage Query

Track API usage, session telemetry, and token consumption across providers. Built-in CLI tools and host API endpoints for querying usage data in real time.

Overview

ScorpioX Code tracks API usage across all supported providers — Anthropic, OpenAI, Google, and Vertex. Usage data includes token consumption (input and output), request counts, and session lifecycle events. All tracking is opt-in and controlled through scorpiox-env.txt.

4
Config keys
2
CLI tools
6
Host API endpoints
8
Event types

Configuration

All usage tracking keys live in scorpiox-env.txt. Both features are disabled by default — set the boolean keys to 1 to enable, then provide the API URL where data should be sent.

Key Type Default Description
USAGE_TRACKING boolean 0 Enable usage/telemetry tracking
Used by: libsxnet, libsxutil, scorpiox-usage
USAGE_API_URL string — API endpoint for usage tracking data
Used by: libsxutil, scorpiox-usage
EMIT_SESSION_TRACKING boolean 0 Enable session event emission
Used by: libsxutil, scorpiox-emit-session, sx
EMIT_SESSION_API_URL string — API endpoint for session event data
Used by: libsxutil, scorpiox-emit-session
scorpiox-env.txt
# Enable API usage tracking
USAGE_TRACKING=1
USAGE_API_URL=https://telemetry.example.com/v1/usage

# Enable session event emission
EMIT_SESSION_TRACKING=1
EMIT_SESSION_API_URL=https://telemetry.example.com/v1/sessions

CLI Tools

Two dedicated C binaries handle usage data collection and session event emission. Both are compiled from the ScorpioX source tree and linked against libsxutil and libsxnet.

scorpiox-usage 517 lines of C

API usage tracker — queries and reports token consumption, cost, and request counts per provider and model.

scorpiox-emit-session 590 lines of C

Session event emitter — pushes lifecycle events (thinking, tool-start, tool-done, complete, error, idle) to the host API for real-time monitoring.

Example: query usage
# Run the usage tracker directly
scorpiox-usage

# The tool reads USAGE_TRACKING and USAGE_API_URL from scorpiox-env.txt
# and reports token consumption per provider/model
Example: emit session events
# Emit session events to the host API
scorpiox-emit-session

# Reads EMIT_SESSION_TRACKING and EMIT_SESSION_API_URL
# Pushes lifecycle events: thinking, tool-start, tool-done, complete, error, idle

Host API Endpoints

The scorpiox-host server exposes REST endpoints for querying session state and events. These are served from the host process that manages multiple concurrent coding sessions.

Method Path Description
GET /status Server summary — returns version, port, uptime, session count, active count, and total events.
GET /sessions List all sessions — returns JSON array with id, state, last_event timestamp, event_count, and model/provider metadata.
GET /sessions/:id Session detail — full session info including state, event count, recent events (last 10), model, provider, cwd, and start_time.
GET /sessions/:id/events Get session events — returns recent events as NDJSON (newline-delimited JSON).
POST /sessions/:id/events Fire session event — pushes an event to the session ring buffer. Events: thinking, tool-start, tool-done, complete, error, idle, user-message, compact.
POST /sessions/:id/register Register a session — creates or updates a session with a display name, sets state to idle.
Example: query sessions via API
# List all active sessions
curl http://localhost:8080/sessions

# Get detail for a specific session
curl http://localhost:8080/sessions/abc123

# Stream events from a session
curl http://localhost:8080/sessions/abc123/events

# Fire an event
curl -X POST http://localhost:8080/sessions/abc123/events \
  -H "Content-Type: application/json" \
  -d '{"event":"thinking","data":"analyzing code"}'

Session Tracking

ScorpioX Code defines 8 event types that flow through the session tracking pipeline. Each event is stored in a ring buffer on the host and can be queried via the REST API or streamed as NDJSON.

🧠
thinking Model is generating a response with extended thinking enabled.
🔧
tool-start A tool invocation has begun (bash, file edit, web search, etc.).
✅
tool-done A tool invocation has completed with result.
🏁
complete The model has finished its response turn.
❌
error An error occurred during processing.
💤
idle Session is idle, waiting for user input.
💬
user-message User sent a new message to the session.
📦
compact Context was compacted to free token space.
Event JSON format
// Each event in the NDJSON stream
{
  "event": "tool-start",
  "data": "Bash: git status",
  "timestamp": "2026-05-29T09:42:00Z",
  "session_id": "abc123"
}

Examples

Full setup: enable usage tracking + session events
# 1. Edit scorpiox-env.txt
USAGE_TRACKING=1
USAGE_API_URL=https://your-api.example.com/usage
EMIT_SESSION_TRACKING=1
EMIT_SESSION_API_URL=https://your-api.example.com/sessions

# 2. Start a coding session — events are emitted automatically
sx "refactor the auth module"

# 3. Query session state from another terminal
curl -s http://localhost:8080/sessions | jq '.'

# 4. Watch events in real time
curl -sN http://localhost:8080/sessions/$(curl -s http://localhost:8080/sessions | jq -r '.[0].id')/events
Register and monitor a session
# Register a named session
curl -X POST http://localhost:8080/sessions/my-session/register \
  -H "Content-Type: application/json" \
  -d '{"session":"auth-refactor"}'

# Check server status
curl http://localhost:8080/status
# {"version":"...","uptime":3600,"sessions":3,"active":1,"events":142}