How to track user token usage in a Forge app published on Marketplace?

[Vitheya Monikha]

I have built a Jira app using Forge with AI functionality where token usage is restricted and currently working fine. The app is now published on the Atlassian Marketplace and is being used by multiple customers.

Challenge:
We are unable to track per-user or per-tenant token usage.

Current setup:

• AI API key is stored securely using Forge/Jira storage
• No external database is used
• Token limiting is implemented, but usage visibility is missing

Questions: What is the recommended way to track token usage in a Forge app?

Thanks in advance!

[Alexander Nilsson]

Hello Vitheya,

thanks for your question which is important for anyone offering AI-based Forge apps through the Marketplace.

Unfortunately I haven’t tried implementing detailed token usage tracking myself yet, but I found some relevant information in the official Atlassian Forge documentation that may help point you in the right direction.

Currently, Forge doesn’t provide a built-in mechanism to track per-user or per-tenant API token usage out of the box. Since Forge storage is scoped to the app and environment, it’s well-suited for storing usage counters or summaries per tenant (installation), but not for detailed per-user analytics unless you implement that logic yourself.

Here are a few approaches that align with Atlassian’s recommended practices:

1. Use Forge Storage API for per-tenant tracking
   You can increment and persist usage counts using Forge Storage API and the runtime reference.
   Example: Store usage under a key like usage:{accountId} or usage:{tenantId}.
   Reset or aggregate the data periodically (for example, via scheduled triggers).
2. Integrate an external usage tracking service
   If you need richer analytics or billing-grade tracking, consider connecting to an external service such as AWS DynamoDB, Firebase, or your own backend.
   Forge apps can securely send usage data via custom resolvers in a Forge Bridge or HTTP resolver.
   Make sure to comply with Forge data residency and storage guidelines.
3. Tenant-level visibility through Forge Metrics
   The Forge Metrics dashboard provides high-level insight into invocations, errors, and performance per installation, though it doesn’t expose user-level token consumption directly.

In short, for fine-grained tracking (like per-user token usage), the best practice is to:

• Use Forge storage if you only need lightweight counting.
• Or introduce a minimal external service if you need robust usage visibility or cross-tenant reporting.

Hope that helps clarify the options! You can also check out the official docs on Forge storage and external data connections for more details and examples.

Greetings and Happy New Year,
Alex