Product usage

Usage is tracked per product for the signed-in user. The organization comes from the access token. Each user gets an allowance for every billing period. It goes back to the full limit at resetsAt.


const usage = await squire.user.getUsage();
 
const scribe = usage.products.find((product) => product.productId === 'squire_scribe');
 
console.log(scribe);
// { productId: "squire_scribe", plan: "free", used: 3, limit: 10, remaining: 7, resetsAt: "2026-06-01T00:00:00Z" }

Response shape

getUsage() returns a products list with one entry per product. Look your product up by its productId rather than by position, so that your code keeps working as products are added:

Name	Type	Default
`productId`	`string` Identifier of the product this allowance applies to, for example “squire_scribe”.
`plan`	`string` Plan the user is on, for example “free” or “standard”. Read the limit below for the allowance actually in force.
`used`	`number` Amount used so far this period.
`limit`	`number` Total amount allowed for the period on the user’s plan.
`remaining`	`number` Amount still available this period (limit minus used).
`resetsAt`	`string` ISO 8601 timestamp, always UTC, at which the allowance goes back to the full limit. This moment belongs to the next period: a consultation started exactly then, or later, counts towards the new allowance.

Running out of allowance

Squire checks the limit on the server, so you do not need to check it yourself before each recording. Once a user has no allowance left, startRecording fails with HTTP 402 and the code consultation_quota_exceeded:


try {
  const consultation = await squire.startRecording();
} catch (error) {
  if (
    error instanceof Squire.ApiError &&
    error.code === Squire.CONSULTATION_QUOTA_EXCEEDED
  ) {
    // Show an upgrade prompt
    return;
  }
  throw error;
}

Handling this error is all you need to do. We do recommend showing the usage somewhere in your app, such as a counter or a warning when users get close to their limit, so that running out does not come as a surprise.

Reading usage from your backend

To show usage outside the SDK, your backend can read the same numbers with your API key, without requesting an access token:


curl "https://api.squire.eu/api/v1/external/users/USER_ID/usage/" \
  -H "X-Api-Key: YOUR_API_KEY"

USER_ID is the user ID you passed when you created the user. The response is the same, except that the field names stay in snake_case (product_id, resets_at). See the usage endpoint API reference .