# 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