Use the Deferred tier to run asynchronous, multi-turn Gemini model calls for custom agents at a discounted rate on Gemini Enterprise Agent Platform. On the Interactions API, Agent Platform queues each deferred turn for background execution within a 24-hour target and retains state for 7 days.
The Deferred tier fits latency-tolerant agentic workloads that need per-turn control, such as the following:
- Multi-step coding and security agents: Repository vulnerability scans, automated code migrations, and regression triage.
- Document and research pipelines: Technical design reviews, financial backtesting, and multi-document synthesis with tool calling.
- Offline agent evaluations: Large-scale quality benchmarks that chain
previous_interaction_idturns without real-time latency constraints.
To compare all compute models, see Consumption options. To schedule Agent Development Kit (ADK) agents or managed runs on the Gemini Deep Research Agent, see Autonomous agent scheduling.
Supported models and locations
The Deferred tier is supported exclusively on the global endpoint
(locations/global on aiplatform.googleapis.com). Sending a request with
service_tier="deferred" to a regional endpoint or to the us or eu
multi-region endpoints returns HTTP 400 ("code": "invalid_request").
The following mainline Gemini models support the
Deferred tier on the global endpoint:
- Gemini 4 Carbon (
gemini-4-carbon) - Gemini 4 Argon (
gemini-4-argon) - Gemini 3.8 Flash (
gemini-3.8-flash) - Gemini 3.7 Flash (
gemini-3.7-flash) - Gemini 3.6 Flash (
gemini-3.6-flash) - Gemini 3.5 Flash-Lite (
gemini-3.5-flash-lite) - Gemini 3.5 Flash (
gemini-3.5-flash) - Gemini 3.1 Flash-Lite (
gemini-3.1-flash-lite) - Gemini 3.1 Pro (
gemini-3.1-pro-preview)
If your project has allowlist access through your Cloud de Confiance by S3NS account team, you can also use the following Cyber models:
- Gemini 4 Carbon for cyber (
gemini-4-carbon-cyber-permissive) - Gemini 4 Argon Cyber Permissive (
gemini-4-argon-cyber-permissive)
Before you begin
In an existing billing-enabled Cloud de Confiance by S3NS project, complete the following prerequisite setup steps:
-
Install the Google Cloud CLI.
-
Configure the gcloud CLI to use your federated identity.
For more information, see Sign in to the gcloud CLI with your federated identity.
-
To initialize the gcloud CLI, run the following command:
gcloud init -
Verify that you have the permissions required to complete this guide.
Enable the Agent Platform API, if it is not already enabled:
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.gcloud services enable aiplatform.googleapis.com
-
Create local authentication credentials for your user account:
gcloud auth application-default login
If an authentication error is returned, confirm that you have signed in to the gcloud CLI with your federated identity.
Required roles
To get the permissions that you need to create, monitor, and cancel deferred model calls, ask your administrator to grant you the following IAM roles on your Cloud de Confiance by S3NS project:
-
Create, poll, cancel, and delete deferred interactions:
Agent Platform User (
roles/aiplatform.user) -
Monitor deferred interactions (read-only):
Agent Platform Viewer (
roles/aiplatform.viewer) -
Read multimodal input files from Cloud Storage (optional):
Storage Object Viewer (
roles/storage.objectViewer)
For more information about granting roles, see Manage access to projects, folders, and organizations.
You might also be able to get the required permissions through custom roles or other predefined roles.
Install the Google Gen AI SDK
If you use a client library, install or upgrade the Google Gen AI SDK
(@google/genai >= 2.32.0 or google-genai >= 2.34.0) in your development
environment:
Node.js
npm install @google/genai@latest
Python
pip install --upgrade "google-genai>=2.34.0"
Create and manage deferred model calls
Run the following procedures in the environment that you set up in Before you begin. The REST samples authenticate with your gcloud CLI credentials, and the Google Gen AI SDK samples use Application Default Credentials (ADC). If a call returns an error, see Troubleshoot.
Create a deferred model call
Submit an asynchronous turn by calling interactions.create with
service_tier="deferred", background=true, and store=true. Omit stream
or set it to false. Before you run a sample, replace
PROJECT_ID with your Cloud de Confiance by S3NS project ID, such as
my-agent-project.
REST
Before using any of the request data, make the following replacements:
PROJECT_ID: your Cloud de Confiance by S3NS project ID, such asmy-agent-project.
HTTP method and URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
Request JSON body:
{
"model": "gemini-4-argon",
"input": "In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
"service_tier": "deferred",
"background": true,
"store": true
}
To send your request, expand one of these options:
The response returns a JSON payload similar to the following:
{
"id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
"model": "gemini-4-argon",
"status": "queued",
"service_tier": "deferred",
"steps": []
}
Node.js
import { GoogleGenAI } from "@google/genai";
async function createDeferredInteraction(projectId) {
const ai = new GoogleGenAI({
enterprise: true,
project: projectId,
location: "global",
});
const interaction = await ai.interactions.create({
model: "gemini-4-argon",
input:
"In two sentences, explain how a circuit breaker differs from exponential backoff in a distributed microservice architecture.",
service_tier: "deferred",
background: true,
store: true,
});
console.log(`Interaction ID: ${interaction.id}`);
console.log(`Status: ${interaction.status}`);
console.log(`Service tier: ${interaction.service_tier}`);
return interaction.id ?? "";
}
await createDeferredInteraction("PROJECT_ID");
The output is similar to the following:
Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred
Python
from google import genai
def create_deferred_interaction(project_id: str) -> str:
client = genai.Client(
enterprise=True,
project=project_id,
location="global",
)
interaction = client.interactions.create(
model="gemini-4-argon",
input=(
"In two sentences, explain how a circuit breaker differs from "
"exponential backoff in a distributed microservice architecture."
),
service_tier="deferred",
background=True,
store=True,
)
print(f"Interaction ID: {interaction.id}")
print(f"Status: {interaction.status}")
print(f"Service tier: {interaction.service_tier}")
return interaction.id or ""
create_deferred_interaction("PROJECT_ID")
The output is similar to the following:
Interaction ID: v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0
Status: queued
Service tier: deferred
Poll status and retrieve token usage
Poll interactions.get with backoff while status is queued or
in_progress. When the turn reaches a final status, read output_text and
usage.
The Deferred tier targets completing 95% of turns within 24 hours
without a credit-backed latency SLA. The following table describes the status
values of an Interaction resource:
| Status | Final | Meaning and next step |
|---|---|---|
queued |
No | Accepted and waiting for capacity. Poll interactions.get with backoff. Don't request stream=true yet. |
in_progress |
No | Running. Continue to poll interactions.get, or attach an SSE stream with stream=true. |
requires_action |
Yes | The turn ended on a model-emitted function_call step. Run the tool, and then create a new turn with previous_interaction_id. |
requires_continuation |
Yes | A long-decode turn stopped with partial output and a continuation_token. Resume with previous_interaction_id and continuation_token, omit input, and raise max_output_tokens. |
completed |
Yes | The turn finished. Read output_text and usage, or pass id as previous_interaction_id on the next turn. |
incomplete |
Yes | The turn stopped early, such as when it reached max_output_tokens. Inspect the partial steps and usage. |
failed |
Yes | The turn hit a runtime error or exceeded the 24-hour completion window. The API doesn't use an expired status. Inspect error, and then submit a new request. |
cancelled |
Yes | A call to interactions.cancel stopped the turn before it finished. |
If a long-decode turn ends as requires_continuation, resume it by calling
interactions.create with previous_interaction_id, continuation_token,
background=true, store=true, and service_tier="deferred". Omit input and
set max_output_tokens higher than the tokens generated so far. To learn how
each final status is billed, see Pricing and billing.
Before you run a sample, make the following replacements:
PROJECT_ID: your Cloud de Confiance by S3NS project ID, such asmy-agent-project.INTERACTION_ID: the interaction ID returned when you created the deferred model call, such asv1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
Before using any of the request data, make the following replacements:
PROJECT_ID: your Cloud de Confiance by S3NS project ID, such asmy-agent-project.INTERACTION_ID: the interaction ID returned when you created the deferred model call, such asv1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
HTTP method and URL:
GET https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID
To send your request, expand one of these options:
The response returns a JSON payload similar to the following:
{
"id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
"model": "gemini-4-argon",
"status": "completed",
"service_tier": "deferred",
"steps": [
{
"type": "model_output",
"content": [
{
"type": "text",
"text": "Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again."
}
]
}
],
"usage": {
"total_input_tokens": 27,
"total_output_tokens": 41,
"total_tokens": 68
}
}
Node.js
import { GoogleGenAI } from "@google/genai";
const PENDING_STATES = new Set(["queued", "in_progress"]);
const MAX_DELAY_MS = 30000;
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
async function waitForDeferredInteraction(projectId, interactionId) {
const ai = new GoogleGenAI({
enterprise: true,
project: projectId,
location: "global",
});
let delayMs = 5000;
let current = await ai.interactions.get(interactionId);
while (PENDING_STATES.has(current.status)) {
await sleep(delayMs);
delayMs = Math.min(delayMs * 2, MAX_DELAY_MS);
current = await ai.interactions.get(interactionId);
}
console.log(`Status: ${current.status}`);
if (current.status === "failed") {
throw new Error(`Deferred turn failed: ${JSON.stringify(current.error)}`);
}
if (current.output_text) {
console.log(current.output_text);
}
if (current.usage) {
console.log(`Input tokens: ${current.usage.total_input_tokens}`);
console.log(`Output tokens: ${current.usage.total_output_tokens}`);
console.log(`Total tokens: ${current.usage.total_tokens}`);
}
return current.output_text ?? "";
}
await waitForDeferredInteraction(
"PROJECT_ID",
"INTERACTION_ID",
);
The output is similar to the following:
Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68
Python
import time
from google import genai
PENDING_STATES = frozenset({"queued", "in_progress"})
MAX_DELAY_SECONDS = 30.0
def wait_for_deferred_interaction(
project_id: str,
interaction_id: str,
) -> str:
client = genai.Client(
enterprise=True,
project=project_id,
location="global",
)
delay_seconds = 5.0
current = client.interactions.get(interaction_id)
while current.status in PENDING_STATES:
time.sleep(delay_seconds)
delay_seconds = min(delay_seconds * 2.0, MAX_DELAY_SECONDS)
current = client.interactions.get(interaction_id)
print(f"Status: {current.status}")
if current.status == "failed":
raise RuntimeError(f"Deferred turn failed: {current.error}")
if current.output_text:
print(current.output_text)
if current.usage:
print(f"Input tokens: {current.usage.total_input_tokens}")
print(f"Output tokens: {current.usage.total_output_tokens}")
print(f"Total tokens: {current.usage.total_tokens}")
return current.output_text or ""
wait_for_deferred_interaction(
"PROJECT_ID",
"INTERACTION_ID",
)
The output is similar to the following:
Status: completed
Exponential backoff increases the wait time between retries to give a struggling service time to recover. A circuit breaker stops sending requests once failures pass a threshold, failing fast until the downstream service is healthy again.
Input tokens: 27
Output tokens: 41
Total tokens: 68
Optional: Stream output while a call runs
After interactions.get reports status="in_progress", you can attach a
Server-Sent Events (SSE) stream with stream=true and resume dropped
connections with last_event_id:
REST
Append ?stream=true to the interactions.get URL. When reconnecting, also
append &last_event_id=EVENT_ID, replacing
EVENT_ID with the last received event ID.
Node.js
Iterate over
await ai.interactions.get(interactionId, { stream: true,
last_event_id: lastEventId }), record event.event_id, and read
event.delta?.text on step.delta events.
Python
Iterate over
client.interactions.get(interaction_id, stream=True,
last_event_id=last_event_id), record event.event_id, and read
event.delta.text on step.delta events.
For more information about SSE streaming and reconnection, see the Interactions API developer guide.
Chain multi-turn deferred workflows
Continue a multi-turn conversation or return tool execution results by passing
the id of a completed or requires_action interaction in
previous_interaction_id. Turn-scoped fields such as tools,
system_instruction, and generation_config don't carry over automatically,
so pass them on each turn that requires them. Chained turns remain eligible for
implicit context caching, though cached prefixes
might expire across multi-hour queue waits. For tool-result step schemas, see
the Interactions API developer guide.
Before you run a sample, make the following replacements:
PROJECT_ID: your Cloud de Confiance by S3NS project ID, such asmy-agent-project.PREVIOUS_INTERACTION_ID: the ID of the precedingcompletedorrequires_actionturn, such asv1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
REST
Before using any of the request data, make the following replacements:
PROJECT_ID: your Cloud de Confiance by S3NS project ID, such asmy-agent-project.PREVIOUS_INTERACTION_ID: the completed or action-required interaction ID from the preceding turn, such asv1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.
HTTP method and URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions
Request JSON body:
{
"model": "gemini-4-argon",
"previous_interaction_id": "PREVIOUS_INTERACTION_ID",
"input": "Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
"service_tier": "deferred",
"background": true,
"store": true
}
To send your request, expand one of these options:
The response returns a JSON payload similar to the following:
{
"id": "v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0",
"model": "gemini-4-argon",
"previous_interaction_id": "v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0",
"status": "queued",
"service_tier": "deferred",
"steps": []
}
Node.js
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
enterprise: true,
project: "PROJECT_ID",
location: "global",
});
const followUp = await ai.interactions.create({
model: "gemini-4-argon",
previous_interaction_id: "PREVIOUS_INTERACTION_ID",
input:
"Draft a one-paragraph rollout checklist for adding a circuit breaker to a payment gateway client without causing false trips.",
service_tier: "deferred",
background: true,
store: true,
});
console.log(`Follow-up ID: ${followUp.id} (${followUp.status})`);
The output is similar to the following:
Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)
Python
from google import genai
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
follow_up = client.interactions.create(
model="gemini-4-argon",
previous_interaction_id="PREVIOUS_INTERACTION_ID",
input=(
"Draft a one-paragraph rollout checklist for adding a circuit "
"breaker to a payment gateway client without causing false trips."
),
service_tier="deferred",
background=True,
store=True,
)
print(f"Follow-up ID: {follow_up.id} ({follow_up.status})")
The output is similar to the following:
Follow-up ID: v1_Ch1Lm9RUXhPNlJqS1lBMk56UjdVOGdnPT0 (queued)
Cancel a deferred model call
To stop a deferred interaction whose status is queued or in_progress, call
interactions.cancel. Calling interactions.cancel on an interaction in any
other status returns HTTP 409 ("code": "aborted"). To learn how cancellation
affects billing, see Pricing and billing.
Before you run a sample, make the following replacements:
PROJECT_ID: your Cloud de Confiance by S3NS project ID, such asmy-agent-project.INTERACTION_ID: the ID of aqueuedorin_progressinteraction, such asv1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.
REST
Before using any of the request data, make the following replacements:
PROJECT_ID: your Cloud de Confiance by S3NS project ID, such asmy-agent-project.INTERACTION_ID: the ID of a queued or in-progress interaction to cancel, such asv1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.
HTTP method and URL:
POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/interactions/INTERACTION_ID/cancel
To send your request, expand one of these options:
The response returns a JSON payload similar to the following:
{
"id": "v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ",
"model": "gemini-4-argon",
"status": "cancelled",
"service_tier": "deferred"
}
Node.js
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
enterprise: true,
project: "PROJECT_ID",
location: "global",
});
const cancelled = await ai.interactions.cancel("INTERACTION_ID");
console.log(`Status: ${cancelled.status}`);
The output is the following:
Status: cancelled
Python
from google import genai
client = genai.Client(
enterprise=True,
project="PROJECT_ID",
location="global",
)
cancelled = client.interactions.cancel("INTERACTION_ID")
print(f"Status: {cancelled.status}")
The output is the following:
Status: cancelled
Pricing, quotas, and security controls
Review billing rules, quotas, payload limits, and security controls before you run production workloads on the Deferred tier.
Pricing and billing
Deferred model calls are billed at a 50% discount compared to Standard pay-as-you-go rates for input, output, and thinking tokens. Billing follows these rules:
- Discount stacking: The deferred discount stacks with contract discounts and implicit context caching token discounts, applying on top of the cached rate.
- No fallback to standard rates: Deferred requests never spill over or downgrade to Standard PayGo, so they aren't billed at undiscounted on-demand rates.
- Billing by model call: Each model call that a turn makes is billed.
Turns that end as
completed,incomplete,requires_action, orrequires_continuationare billed at the deferred rate. - Cancelled turns: A turn that you cancel while it's
queuedisn't billed. If you cancel a turn while it'sin_progress, model calls that already started are billed, including a call that's interrupted mid-generation. - Failed turns: Single-call turns that end as
failed, including turns that exceed the 24-hour completion window, aren't billed. In a multi-step server-side tool loop, completed model calls before a failure are billed, but the failed call isn't. - Chained turns: Each turn in a
previous_interaction_idchain is billed on its own. Cancelling a later turn, or a later turn failing, doesn't change the charges for earlier turns.
For per-model token rates, see the Agent Platform pricing page.
Quotas, payload limits, and retention
The Deferred tier doesn't have its own model-call quota. Deferred
calls share the Flex pay-as-you-go quota
(flex_requests_per_minute_per_project_per_base_model, 3,000 RPM), which
is checked on each model call after interactions.create returns queued. Key
project quotas and system limits include the following:
- Creation and concurrency quotas: Up to 100 RPM or unlimited for
stateful_genai_interaction_creationsat creation time. Up to 500concurrent_interaction_generations, depending on your quota tier. - Daily stateful throughput (fixed): 240 GiB per day written and 480 GiB per day read per project.
- Payload and retention limits: Up to 9.75 MiB uncompressed HTTP
body per
interactions.createcall, and 7-day state retention. Chains support up to 100 distinct Cloud Storage (gs://) URIs.
For the complete quota table and console instructions, see Deferred tier quotas and limits.
Security and compliance controls
Because the Deferred tier queues and persists state on the global
endpoint, verify that its supported governance controls match your compliance
requirements:
- Supported controls:
VPC Service Controls
(VPC-SC; external
mcp_servertools aren't allowed inside a perimeter), Access Transparency (AXT), Cloud Audit Logs, and FedRAMP High. - Unsupported controls: Stateless zero data retention (
store=falseand enforcingconstraints/vertexai.disableAPIStorageboth return HTTP400with"code": "invalid_request"), Customer-managed encryption keys (CMEK), Data residency, DoD IL5, and ITAR.
For the full feature matrix, see Security controls for Generative AI.
Troubleshoot
The following table describes common errors on the Deferred tier and how to resolve them:
| Error or status | Common causes | Resolution |
|---|---|---|
400 (error.code: "invalid_request"; endpoint, flags, or model) |
Non-global endpoint, unsupported model, or invalid background, store, or stream flags on interactions.create. |
Target locations/global with a supported model, set background=true and store=true, and omit stream=true. |
400 (error.code: "invalid_request"; payload, URIs, or tools) |
Uncompressed body exceeds 9.75 MiB, chain exceeds 100 gs:// URIs, or external mcp_server tools inside VPC-SC. |
Pass large files as gs:// URIs (at most 100 per chain), and omit external mcp_server tools inside VPC-SC. |
400 (error.code: "invalid_request" on interactions.create; status: "FAILED_PRECONDITION" on interactions.delete) |
|
|
401 (status: "UNAUTHENTICATED" or error.code: "authentication") |
Your gcloud CLI credentials (REST samples) or ADC (Google Gen AI SDK samples) are missing or expired. | For REST samples, run gcloud auth login. For Google Gen AI SDK samples, run gcloud auth application-default login. Then retry the request. |
403 (status: "PERMISSION_DENIED" or error.code: "permission_denied") |
|
Grant roles/aiplatform.user. For Cloud Storage inputs, also grant roles/storage.objectViewer. |
404 (error.code: "not_found"; status: "NOT_FOUND" on interactions.delete) |
The interaction or previous_interaction_id doesn't exist or was deleted. It might also belong to a non-global endpoint or be older than the 7-day retention period. |
Check the interaction ID on the global endpoint. If the parent turn expired, start a new chain without previous_interaction_id. |
409 (error.code: "aborted") |
interactions.cancel targets an interaction that's already in a final status: requires_action, requires_continuation, completed, incomplete, failed, or cancelled. |
Check status with interactions.get first. You can cancel only queued and in_progress interactions. |
429 (error.code: "too_many_requests") |
The project exceeded a per-project quota, such as the interaction creation rate, concurrent interaction generations, or daily stateful throughput. |
|
status="failed" |
|
|
What's next
Explore related guides and reference documentation for asynchronous and stateful Gemini workloads:
- Compare compute models in Consumption options.
- Build stateful multi-turn applications in the Interactions API developer guide.
- Schedule ADK agents and managed research runs in Autonomous agent scheduling.
- Explore method schemas in the Interactions API reference.