> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentgate.mynewapi.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Usage Records

> Get usage records with optional filters

# List Usage Records

Returns token usage records with optional filtering by work order, run, model, and date range.

## Request

<ParamField query="workOrderId" type="string">
  Filter by work order ID
</ParamField>

<ParamField query="runId" type="string">
  Filter by run ID
</ParamField>

<ParamField query="model" type="string">
  Filter by model name (e.g., `claude-sonnet-4-20250514`)
</ParamField>

<ParamField query="startDate" type="string">
  Start date filter (ISO 8601)
</ParamField>

<ParamField query="endDate" type="string">
  End date filter (ISO 8601)
</ParamField>

<ParamField query="limit" type="integer" default="100">
  Maximum number of records to return (1-1000)
</ParamField>

<ParamField query="offset" type="integer" default="0">
  Number of records to skip for pagination
</ParamField>

```bash theme={null}
curl "https://agentgate.mynewapi.com/api/v1/usage?limit=50&model=claude-sonnet-4-20250514" \
  -H "Authorization: Bearer YOUR_API_KEY"
```

## Response

<ResponseField name="success" type="boolean" required>
  Indicates if the request was successful
</ResponseField>

<ResponseField name="data" type="array" required>
  Array of usage records

  <Expandable title="properties">
    <ResponseField name="id" type="string" required>
      Unique usage record ID
    </ResponseField>

    <ResponseField name="workOrderId" type="string" required>
      Associated work order ID
    </ResponseField>

    <ResponseField name="runId" type="string" required>
      Associated run ID
    </ResponseField>

    <ResponseField name="iteration" type="number" required>
      Iteration number within the run
    </ResponseField>

    <ResponseField name="model" type="string" required>
      Model used (e.g., `claude-sonnet-4-20250514`)
    </ResponseField>

    <ResponseField name="inputTokens" type="number" required>
      Number of input tokens
    </ResponseField>

    <ResponseField name="outputTokens" type="number" required>
      Number of output tokens
    </ResponseField>

    <ResponseField name="cachedInputTokens" type="number" required>
      Number of cached input tokens
    </ResponseField>

    <ResponseField name="costUsd" type="number" required>
      Estimated cost in USD
    </ResponseField>

    <ResponseField name="durationMs" type="number" required>
      Execution duration in milliseconds
    </ResponseField>

    <ResponseField name="timestamp" type="string" required>
      ISO 8601 timestamp of the usage
    </ResponseField>
  </Expandable>
</ResponseField>

## Example Response

```json theme={null}
{
  "success": true,
  "data": [
    {
      "id": "usage_abc123",
      "workOrderId": "wo_xyz789",
      "runId": "run_def456",
      "iteration": 1,
      "model": "claude-sonnet-4-20250514",
      "inputTokens": 15420,
      "outputTokens": 3250,
      "cachedInputTokens": 8000,
      "costUsd": 0.0523,
      "durationMs": 45230,
      "timestamp": "2024-01-15T10:30:00.000Z"
    },
    {
      "id": "usage_def456",
      "workOrderId": "wo_xyz789",
      "runId": "run_def456",
      "iteration": 2,
      "model": "claude-sonnet-4-20250514",
      "inputTokens": 18200,
      "outputTokens": 2100,
      "cachedInputTokens": 12000,
      "costUsd": 0.0412,
      "durationMs": 32100,
      "timestamp": "2024-01-15T10:32:15.000Z"
    }
  ]
}
```

## Use Cases

* Track token usage per work order
* Analyze model costs over time
* Audit execution history
* Generate billing reports