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

# Usage - Increment Agent Queries

> This endpoint allows you to track and charge credits based on AI model token consumption for your organization.

This endpoint is used to register credit consumption based on AI model usage. It tracks token usage (input/output) and automatically calculates the credit cost based on the model provider and configuration.

**Use Cases:**

* Track AI agent interactions and their associated costs
* Bill custom integrations that use AI models
* Monitor and control credit spending per agent or feature
* Implement usage-based billing for your organization

<Note>
  This endpoint requires a valid subscription or sufficient credit balance. The request will fail if the organization has exceeded its usage limits.
</Note>

### Body

<ParamField body="provider" type="string" required>
  The AI model provider. Accepted values:

  * `azure`
  * `azure-2`
  * `openai`
  * `gemini`
  * `deepseek`
  * `bedrock`
</ParamField>

<ParamField body="modelName" type="string" required>
  The specific model name used for the request. Available models per provider:

  | Provider   | Available Models                                                                                                   |
  | ---------- | ------------------------------------------------------------------------------------------------------------------ |
  | `azure`    | `gpt-4o-mini`, `gpt-4o`                                                                                            |
  | `azure-2`  | `gpt-4.1-nano`, `gpt-4.1-mini`, `gpt-4.1`, `gpt-5-nano`, `gpt-5-mini`, `gpt-5-chat`, `gpt-5`                       |
  | `openai`   | `gpt-4.1`, `gpt-4.1-mini`                                                                                          |
  | `gemini`   | `gemini-2.0-flash`, `gemini-2.0-flash-exp`, `gemini-2.5-flash`, `gemini-2.5-pro`, `gemini-3-pro`, `gemini-3-flash` |
  | `deepseek` | `deepseek-chat`, `DeepSeek-V3.2`, `DeepSeek-V3.2-thinking`                                                         |
  | `bedrock`  | `claude-4-sonnet`, `global.anthropic.claude-sonnet-4-20250514-v1:0`                                                |
</ParamField>

<ParamField body="inputTokens" type="integer" default="0">
  The number of input tokens consumed in the request. Must be a non-negative integer.
</ParamField>

<ParamField body="outputTokens" type="integer" default="0">
  The number of output tokens generated in the response. Must be a non-negative integer.
</ParamField>

<ParamField body="coefficient" type="integer">
  Optional multiplier for credit calculation (between 1 and 10). Useful for premium features or custom pricing tiers.
</ParamField>

<ParamField body="feature" type="string" default="agent_run">
  The feature or action that triggered this credit spend (e.g., `agent_run`, `chat_completion`, `embedding`).
</ParamField>

<ParamField body="agentId" type="string">
  Optional. The ID of the agent associated with this usage. Useful for per-agent analytics and billing.
</ParamField>

<ParamField body="metadata" type="object">
  Optional. Additional metadata to associate with this credit event. Can include any custom fields for tracking purposes.
</ParamField>

### Response

<ResponseField name="success" type="boolean">
  Indicates whether the credit spend was successfully recorded.
</ResponseField>

<ResponseField name="organizationId" type="string">
  The ID of the organization that was charged.
</ResponseField>

<ResponseField name="eventId" type="string">
  A unique identifier for this credit spend event. Useful for auditing and reconciliation.
</ResponseField>

<ResponseField name="credits" type="object">
  <Expandable title="Toggle object" defaultOpen>
    <ResponseField name="charged" type="number">
      The actual number of credits charged for this event.
    </ResponseField>

    <ResponseField name="requested" type="number">
      The number of credits that were requested based on the token count.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="model" type="object">
  <Expandable title="Toggle object" defaultOpen>
    <ResponseField name="provider" type="string">
      The AI provider used.
    </ResponseField>

    <ResponseField name="modelName" type="string">
      The model name used.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="tokens" type="object">
  <Expandable title="Toggle object" defaultOpen>
    <ResponseField name="inputTokens" type="integer">
      The input tokens recorded.
    </ResponseField>

    <ResponseField name="outputTokens" type="integer">
      The output tokens recorded.
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl --location --request POST 'https://dashboard.laburen.com/api/usage/increment-agent-queries' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <API_KEY>' \
  --data-raw '{
      "provider": "azure-2",
      "modelName": "gpt-4.1",
      "inputTokens": 1500,
      "outputTokens": 500,
      "feature": "agent_run",
      "agentId": "clxxxxxxxxxxxxxxxxx"
  }'
  ```

  ```javascript JavaScript theme={null}
  const apiUrl = 'https://dashboard.laburen.com/api';
  const apiKey = '<API_KEY>';

  const response = await fetch(`${apiUrl}/usage/increment-agent-queries`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${apiKey}`,
    },
    body: JSON.stringify({
      provider: 'azure-2',
      modelName: 'gpt-4.1',
      inputTokens: 1500,
      outputTokens: 500,
      feature: 'agent_run',
      agentId: 'clxxxxxxxxxxxxxxxxx',
    }),
  });

  const data = await response.json();
  console.log(data);
  ```

  ```python Python theme={null}
  import requests

  api_url = "https://dashboard.laburen.com/api"
  api_key = "<API_KEY>"

  response = requests.post(
      f"{api_url}/usage/increment-agent-queries",
      headers={
          "Content-Type": "application/json",
          "Authorization": f"Bearer {api_key}",
      },
      json={
          "provider": "azure-2",
          "modelName": "gpt-4.1",
          "inputTokens": 1500,
          "outputTokens": 500,
          "feature": "agent_run",
          "agentId": "clxxxxxxxxxxxxxxxxx",
      },
  )

  data = response.json()
  print(data)
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "organizationId": "org_xxxxxxxxxxxx",
    "eventId": "evt_xxxxxxxxxxxx",
    "credits": {
      "charged": 0.045,
      "requested": 0.045
    },
    "model": {
      "provider": "azure-2",
      "modelName": "gpt-4.1"
    },
    "tokens": {
      "inputTokens": 1500,
      "outputTokens": 500
    }
  }
  ```
</ResponseExample>