Report your usage

What the gateway records

• For each request: the route, the model, the latency, the token counts, the cost, the key id and the labels on this page.
• Never the prompt text, the answer text or your key. An administrator can turn on body capture for a route. Ask which routes have it.
• A label that is too long is dropped whole. The gateway never cuts a label, because a cut label would join two different things.

1. Identify the request

Send your client key in one of these headers. The reports attribute the request to the owner of the key. A key with no owner reports as a service account.

2. Select the route

The route decides the model. The page Connect a client tells how to select one. /v1/classify tells which route a text goes to, and why, without a model call.

3. Label the request

These labels are optional. Each one adds a dimension to the reports. The gateway removes the x- headers before it forwards the request to the provider.

• A label is a name. It is never a secret and never prompt text. The gateway stores it.
• Use letters, digits and ._:- in a session id. The PR stamp accepts only these.
• Claude Code sends a session id by itself. You do not need x-session-id for Claude Code.

Examples

# x-client: which tool (max 32 characters)
# x-session-id: one id per run or conversation (max 64)
# x-tags: labels, comma separated
# user (in the body): the person the application acts for
curl https://gateway.example.com/v1/chat/completions \
  -H "Authorization: Bearer ${HOOSHYAR_API_KEY}" \
  -H "Content-Type: application/json" \
  -H "x-client: research-agent" \
  -H "x-session-id: run-2026-10-14-0042" \
  -H "x-tags: team-data,experiment-7" \
  -d '{"model":"auto","user":"alice@example.com","messages":[{"role":"user","content":"ping"}]}'

import os
from openai import OpenAI

client = OpenAI(
    base_url="https://gateway.example.com/v1",
    api_key=os.environ["HOOSHYAR_API_KEY"],
    default_headers={
        "x-client": "research-agent",        # which tool, max 32 characters
        "x-tags": "team-data,experiment-7",  # labels, comma separated
    },
)


def ask(messages, session_id: str, user_email: str):
    return client.chat.completions.create(
        model="auto",
        messages=messages,
        user=user_email,  # the person the application acts for
        extra_headers={"x-session-id": session_id},  # one id per run, max 64 characters
    )

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.example.com/v1",
  apiKey: process.env.HOOSHYAR_API_KEY,
  defaultHeaders: {
    "x-client": "research-agent",        // which tool, max 32 characters
    "x-tags": "team-data,experiment-7",  // labels, comma separated
  },
});

export function ask(messages: OpenAI.ChatCompletionMessageParam[], sessionId: string, userEmail: string) {
  return client.chat.completions.create(
    { model: "auto", messages, user: userEmail }, // the person the application acts for
    { headers: { "x-session-id": sessionId } },   // one id per run, max 64 characters
  );
}

4. Read the answer

The gateway passes these response headers from the provider to your client, and adds one of its own.

• A blocked request normally gets 403 with error.type = guardrail_blocked. It is the answer. Do not retry it.
• Retry only a refused or reset connection, 502, 503 and 504. Send at most 3 tries, with the same x-session-id.

5. Send OpenTelemetry

Use this when your agent calls a model provider directly, not through the gateway. Its usage then appears in the console beside the gateway's own figures. The two are never added together.

• The receiver takes the metrics signal only, as OTLP/JSON over HTTP. Protobuf gets 415. Spans and logs get 404, because they can carry prompt text.
• Send delta temporality. A cumulative point is rejected, because a sum of cumulative points counts the same tokens many times.
• Send your client key in the x-hooshyar-key header. The usage belongs to the owner of that key.
• The gateway stores two metrics: gen_ai.client.token.usage and gen_ai.client.operation.duration. Every other metric name is rejected and named in the answer.
• An SDK that exports protobuf only (the Python SDK) sends to an OpenTelemetry Collector, and the collector sends JSON to the gateway. The second example shows the collector.

export OTEL_METRICS_EXPORTER=otlp
export OTEL_EXPORTER_OTLP_PROTOCOL=http/json                   # JSON only; protobuf is refused
export OTEL_EXPORTER_OTLP_ENDPOINT="https://gateway.example.com/otel"   # the exporter adds /v1/metrics
export OTEL_EXPORTER_OTLP_HEADERS="x-hooshyar-key=${HOOSHYAR_API_KEY}"  # your client key
export OTEL_EXPORTER_OTLP_METRICS_TEMPORALITY_PREFERENCE=delta  # cumulative points are refused
export OTEL_TRACES_EXPORTER=none                                # spans are refused
export OTEL_LOGS_EXPORTER=none                                  # logs are refused
export OTEL_RESOURCE_ATTRIBUTES="service.name=research-agent"   # which tool, max 32 characters

receivers:
  otlp:
    protocols:
      http:
        endpoint: 127.0.0.1:4318
exporters:
  otlphttp/hooshyar:
    endpoint: https://gateway.example.com/otel
    encoding: json
    headers:
      x-hooshyar-key: ${env:HOOSHYAR_API_KEY}
service:
  pipelines:
    metrics:
      receivers: [otlp]
      exporters: [otlphttp/hooshyar]

The attributes

Put these on the resource or on each data point.

What else is stored

These labels, when present: gen_ai.system, gen_ai.provider.name, gen_ai.operation.name, gen_ai.response.model, gen_ai.agent.name, server.address, server.port, error.type, telemetry.sdk.name, telemetry.sdk.language, telemetry.sdk.version. Every other attribute is dropped and its name is recorded. A value longer than 128 characters is dropped whole. Prompt text and completion text are never stored.

The answers

Claude Code can send its own metrics (claude_code.*) the same way. Set the same variables and CLAUDE_CODE_ENABLE_TELEMETRY=1. An administrator may have installed this already in a managed settings file.

6. Stamp a pull request

Use this when your agent opens pull requests. The reports then show what one merged PR cost. An administrator turns the feature on first.

Send one x-session-id per task on every request. Write the same id as one line in the PR body: Hooshyar-Session: <the session id>. Write the same line in a review body to count the review.

A PR with no line, or with two different ids, counts as a merge with no cost. The gateway never guesses a session from the time.

Not for your agent

• /otel/v1/logs and /otel/v1/traces: refused, because they carry prompt text.
• /hooks/v1/events: receives the decisions of the managed Claude Code hooks that an administrator installs. An application does not call it.

Check it

Send one request with your labels. In the console, open Reporting and select the Client or the Session view. An OpenTelemetry export appears under Reported by the agent after the exporter's first interval.