Skip to main content

​
Usage API

Get usage statistics and analytics for your account or workspace.

​
Get User Usage

Get usage statistics for the authenticated user. 
GET /v1/usage

​
Query Parameters

ParameterTypeDescription
startDatestringStart date (ISO 8601)
endDatestringEnd date (ISO 8601)
receptorIdstringFilter by receptor UUID

​
Example Request

const usage = await auvy.usage.getUserUsage({
  startDate: new Date('2024-01-01'),
  endDate: new Date('2024-01-31')
})

​
Example Response

{
  "totalTokens": 150000,
  "totalCost": 12.50,
  "usageByProvider": {
    "openai": {
      "tokens": 100000,
      "cost": 8.00
    },
    "anthropic": {
      "tokens": 50000,
      "cost": 4.50
    }
  },
  "usageByModel": {
    "gpt-4": {
      "tokens": 80000,
      "cost": 6.40
    },
    "claude-3-opus": {
      "tokens": 50000,
      "cost": 4.50
    }
  },
  "usageByReceptor": {
    "receptor-uuid": {
      "receptorId": "receptor-uuid",
      "receptorSlug": "my-receptor",
      "receptorType": "completion",
      "tokens": 75000,
      "cost": 6.25,
      "invokeCount": 42
    }
  }
}

​
Get Workspace Usage

Get usage statistics for a workspace (admin only). 
GET /v1/usage/:workspace_id

​
Path Parameters

ParameterTypeDescription
workspace_idstringWorkspace UUID

​
Query Parameters

ParameterTypeDescription
startDatestringStart date (ISO 8601)
endDatestringEnd date (ISO 8601)
receptorIdstringFilter by receptor UUID

​
Example Request

const usage = await auvy.usage.getWorkspaceUsage('workspace-uuid', {
  startDate: new Date('2024-01-01')
})

​
Usage Statistics Schema

​
Provider Statistics

{
  tokens: number
  cost: number
}

​
Model Statistics

{
  tokens: number
  cost: number
}

​
Receptor Statistics

{
  receptorId: string
  receptorSlug?: string
  receptorType?: string
  tokens: number
  cost: number
  invokeCount: number
}

​
Get Receptor Usage Ranking

Get usage per receptor sorted by tokens, cost, or invoke count (admin only). 
GET /v1/usage/:workspace_id/receptors

​
Path Parameters

ParameterTypeDescription
workspace_idstringWorkspace UUID

​
Query Parameters

ParameterTypeDescription
startDatestringStart date (ISO 8601)
endDatestringEnd date (ISO 8601)
sortBystringSort by tokens, cost, or invokeCount (default: tokens)

​
Example Request

const ranking = await auvy.usage.getWorkspaceReceptorRanking('workspace-uuid', {
  sortBy: 'invokeCount'
})

​
Example Response

{
  "workspaceId": "workspace-uuid",
  "sortBy": "invokeCount",
  "receptors": [
    {
      "receptorId": "receptor-uuid",
      "receptorSlug": "my-receptor",
      "receptorType": "completion",
      "tokens": 75000,
      "cost": 6.25,
      "invokeCount": 42
    }
  ]
}