# Usage & Billing

AlphaNeural includes a small set of **usage and billing** endpoints for tracking spend across API keys, users, and teams. These endpoints are designed for dashboards, internal chargeback, and debugging unusual spend patterns.

All endpoints use the same authentication as the rest of the proxy. The spend log object returned by these endpoints includes request metadata, token counts, and calculated cost.

### View spend logs

Returns spend records. You can filter by `request_id`, `api_key`, `user_id`, and optionally a date range.

When `start_date` and `end_date` are provided:

* `summarize=true` (default) returns **aggregated spend grouped by date** (legacy behaviour)
* `summarize=false` returns **individual log entries** within the date range

**GET** `/spend/logs` 

#### Query parameters

* `request_id` (string, optional). Return logs for a specific request id
* `api_key` (string, optional). Filter by API key
* `user_id` (string, optional). Filter by user id
* `start_date` (string, optional). Start of the window (commonly `YYYY-MM-DD`)
* `end_date` (string, optional). End of the window (commonly `YYYY-MM-DD`)
* `summarize` (boolean, optional, default `true`). Aggregate by date vs return raw logs

#### Example (curl)

```bash
curl https://proxy.alfnrl.io/spend/logs \
  -H "Authorization: Bearer $ALPHANEURAL_API_KEY"
```

Date range with **individual** logs:

```bash
curl "https://proxy.alfnrl.io/spend/logs?start_date=2024-01-01&end_date=2024-01-02&summarize=false" \
  -H "Authorization: Bearer $ALPHANEURAL_API_KEY"
```

#### Response

Returns an array of spend log objects.

***

### View spend tags

Returns spend grouped by request tags. This is useful when you attach tags like `project:search`, `env:staging`, `customer:acme` to requests and want lightweight spend breakdowns.

**GET** `/spend/tags`

#### Query parameters

* `start_date` (string, optional). Start of the window
* `end_date` (string, optional). End of the window

#### Example (curl)

```bash
curl "https://proxy.alfnrl.io/spend/tags?start_date=2022-01-01&end_date=2022-02-01" \
  -H "Authorization: Bearer $ALPHANEURAL_API_KEY"
```

#### Response

Returns an array of spend log objects (tagged).

***

### Calculate spend

Compute cost without running a request (estimate), or compute cost from an existing completion response (post hoc). This endpoint accepts the same inputs used for cost calculation.

**POST** `/spend/calculate` 

#### Request body (one of)

* `model` + `messages` (estimate before calling a model)
* `completion_response` (calculate after you already have a response)

#### Example (curl). Pre-call estimate

```bash
curl https://proxy.alfnrl.io/spend/calculate \
  -H "Authorization: Bearer $ALPHANEURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "anthropic.claude-v2",
    "messages": [{"role":"user","content":"Estimate the cost of this request."}]
  }'
```

#### Example (curl). Post-call calculation

```bash
curl https://proxy.alfnrl.io/spend/calculate \
  -H "Authorization: Bearer $ALPHANEURAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "completion_response": {
      "id": "chatcmpl-123",
      "object": "chat.completion",
      "created": 1677652288,
      "model": "gpt-3.5-turbo-0125",
      "choices": [{
        "index": 0,
        "message": {"role":"assistant","content":"Hello there."},
        "finish_reason": "stop"
      }],
      "usage": {"prompt_tokens": 9, "completion_tokens": 12, "total_tokens": 21}
    }
  }'
```

#### Response

Returns the calculated `cost` as a float


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.alphaneural.io/usage-and-billing.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.