AI Services (advanced): Sessions, large files, and Statistics Follow

This documents assumes you're familiar with a basic AI Services usage.

AI Sessions

Note: As of June 2026, Gemini's /Interactions API is in Beta phase and Google's recommendation is to continue using the stateless generateContent API. Therefore as of now, AI sessions are managed on the ServiceManager side.

AI sessions can be used similary to Forms/HTML services: pass keepAlive=true to a service, then use the returned sessionId when running another service that continues it.

The active sessions will be listed under AI Sessions in Admin -> Sessions:

The ServiceManager remembers and can continue these conversations (for at least AI_SESSION_TIMEOUT_MINUTES), but there's no active session in Gemini nor between ServiceManager and Gemini.

To kill a session, use the Kill button or use a HTTP DELETE request to the /Macro/Sessions API (as in Forms/HTML).

Files API

When an AI service runs with keepAlive=true and one of its inputs is a file, the file will be automatically uploaded to the Gemini's Files API, and sent in the conversation as a URL (totally transparent to the user).

Why is it needed? 
A file of 1 million chars (~1MB) uploaded as string consumes ~250,000 tokens.
The Gemini-2.5-flash context window is 1 million tokens.
Therefore a file of 4MB already fills most of the conversation's context, and becomes a costly prompt. 
 

The Gemini's Files API is the dedicated solution for using files in a convesation, it has a limit of 2GB per file, and files are stored for 48 hours - more than enough for most use cases.

Statistics: Token usage

The statistics screen displays the total AI tokens in the Service Runs and Failures/All Runs tables.

The displayed total AI tokens are calculated by the formula:

totalTokens = inputTokens + outputTokens + reasoningTokens - cachedContentTokens

The Admin->Sessions screen uses the same formula.