Skip to main content

Credit Usage API

The aiUsage query reports how your organization consumes AI credits across the AlphaSense API. Use it to see every GenSearch, ThinkLonger, and DeepResearch operation your team has run — who triggered it, when, which mode, and how many credits it cost.

Typical uses:

  • Monitor consumption — track how your team uses AI features.
  • Analyze patterns — see which AI modes are used most.
  • Plan capacity — make informed decisions about credit allocation.
  • Audit activity — pull historical usage for compliance and reporting.

Prerequisites​

RequirementDetail
API clientAvailable to external API clients only.
Feature flagThe ai:gensearch feature must be enabled on your account. Contact your account team to enable it.
AuthenticationA valid access token. See SSO Authentication or Authentication (Username & Password).

Query​

aiUsage takes an input object and returns a paginated list of usage records. All arguments are optional — call it with no filters to get the most recent activity.

query AiUsage($input: AiUsageInput!) {
  aiUsage(input: $input) {
    nodes {
      messageId
      triggeredAt
      contactEmail
      mode
      platform
      credits
    }
    totalCount
    pageInfo {
      hasNextPage
      hasPreviousPage
      startCursor
      endCursor
    }
  }
}

Input Parameters​

ParameterTypeDescription
fromStringStart date (inclusive), YYYY-MM-DD. Omit for no lower bound.
toStringEnd date (inclusive), YYYY-MM-DD. Omit for no upper bound.
limitIntRecords to return. Default 20, maximum 100.
offsetIntNumber of records to skip. Use with limit to paginate.

Response Fields​

FieldTypeDescription
messageIdStringUnique identifier for the AI request.
triggeredAtDateTimeWhen the AI feature was used (ISO 8601).
contactEmailStringEmail of the user who triggered the request.
modeStringAI mode used (GenSearch, ThinkLonger, DeepResearch).
platformStringClient identifier (your API client ID).
creditsIntNumber of AI credits consumed.
totalCountIntTotal records matching your filters.
pageInfoObjectCursor flags: hasNextPage, hasPreviousPage, startCursor, endCursor.

Get recent AI usage​

Retrieve the 20 most recent AI operations.

import os
import requests

ACCESS_TOKEN = os.environ["ALPHASENSE_ACCESS_TOKEN"]  # see Authentication guide

headers = {
    "x-api-key": os.environ["ALPHASENSE_API_KEY"],
    "clientid": os.environ["ALPHASENSE_CLIENT_ID"],
    "Authorization": f"Bearer {ACCESS_TOKEN}",
    "Content-Type": "application/json",
}

query = """
query AiUsage($input: AiUsageInput!) {
  aiUsage(input: $input) {
    nodes { messageId triggeredAt contactEmail mode credits }
    totalCount
  }
}
"""

variables = {"input": {"limit": 20, "offset": 0}}

response = requests.post(
    "https://api.alpha-sense.com/gql",
    headers=headers,
    json={"query": query, "variables": variables},
)
print(response.json())

Example Response​

{
  "data": {
    "aiUsage": {
      "nodes": [
        {
          "messageId": "msg-abc123",
          "triggeredAt": "2025-11-19T10:30:00.000Z",
          "contactEmail": "user@company.com",
          "mode": "GenSearch",
          "credits": 10
        },
        {
          "messageId": "msg-def456",
          "triggeredAt": "2025-11-19T10:25:00.000Z",
          "contactEmail": "analyst@company.com",
          "mode": "ThinkLonger",
          "credits": 25
        }
      ],
      "totalCount": 1250
    }
  }
}

More examples​

Filter by date range​

Pull usage for a single month — useful for reporting and credit reconciliation.

query MonthlyUsage {
  aiUsage(input: {from: "2025-11-01", to: "2025-11-30", limit: 100, offset: 0}) {
    nodes {
      triggeredAt
      contactEmail
      mode
      credits
    }
    totalCount
  }
}

Total credits used​

Aggregate credits over a period in your application layer.

// Sum all credits, and break the total down by mode
const records = response.data.aiUsage.nodes

const totalCredits = records.reduce((sum, r) => sum + r.credits, 0)

const creditsByMode = records.reduce((acc, r) => {
  acc[r.mode] = (acc[r.mode] || 0) + r.credits
  return acc
}, {})

Usage for a specific user​

The query returns all usage for your client. To report on one user, filter by contactEmail after you receive the results.

const userRecords = response.data.aiUsage.nodes.filter(
  r => r.contactEmail === 'analyst@company.com',
)

Pagination​

Results are paged with limit and offset. The default limit is 20 and the maximum is 100; use 50–100 for batch processing. Check pageInfo.hasNextPage to decide whether to fetch more, and advance offset by your limit each request.

async function fetchAllUsage(from, to) {
  const limit = 100
  let offset = 0
  let hasMore = true
  const all = []

  while (hasMore) {
    const response = await fetchUsage(from, to, limit, offset) // your POST helper
    all.push(...response.data.aiUsage.nodes)
    hasMore = response.data.aiUsage.pageInfo.hasNextPage
    offset += limit
  }
  return all
}

Error handling​

Feature not enabled​

{
  "errors": [
    {
      "message": "No permission to access AI GenSearch feature",
      "extensions": {"code": "BAD_USER_INPUT"}
    }
  ]
}

This will only be available if you are on a usage based plan.

Related pages