Use the Deferred tier

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_id turns 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:

If your project has allowlist access through your Cloud de Confiance by S3NS account team, you can also use the following Cyber models:

Before you begin

In an existing billing-enabled Cloud de Confiance by S3NS project, complete the following prerequisite setup steps:

  1. Install the Google Cloud CLI.

  2. Configure the gcloud CLI to use your federated identity.

    For more information, see Sign in to the gcloud CLI with your federated identity.

  3. To initialize the gcloud CLI, run the following command:

    gcloud init
  4. Verify that you have the permissions required to complete this guide.

  5. Enable the Agent Platform API, if it is not already enabled:

    Roles required to enable APIs

    To enable APIs, you need the serviceusage.services.enable permission. 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
  6. 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:

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 as my-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 as my-agent-project.
  • INTERACTION_ID: the interaction ID returned when you created the deferred model call, such as v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

REST

Before using any of the request data, make the following replacements:

  • PROJECT_ID: your Cloud de Confiance by S3NS project ID, such as my-agent-project.
  • INTERACTION_ID: the interaction ID returned when you created the deferred model call, such as v1_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 as my-agent-project.
  • PREVIOUS_INTERACTION_ID: the ID of the preceding completed or requires_action turn, such as v1_ChpJd25XUXhPNlJqS1lBMk56UjdVOGdnPT0.

REST

Before using any of the request data, make the following replacements:

  • PROJECT_ID: your Cloud de Confiance by S3NS project ID, such as my-agent-project.
  • PREVIOUS_INTERACTION_ID: the completed or action-required interaction ID from the preceding turn, such as v1_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 as my-agent-project.
  • INTERACTION_ID: the ID of a queued or in_progress interaction, such as v1_ChpQcTNuWkVrN0xmUjJ4Yk1oVzhkSmc9PQ.

REST

Before using any of the request data, make the following replacements:

  • PROJECT_ID: your Cloud de Confiance by S3NS project ID, such as my-agent-project.
  • INTERACTION_ID: the ID of a queued or in-progress interaction to cancel, such as v1_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, or requires_continuation are billed at the deferred rate.
  • Cancelled turns: A turn that you cancel while it's queued isn't billed. If you cancel a turn while it's in_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_id chain 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_creations at creation time. Up to 500 concurrent_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.create call, 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:

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)
  • The constraints/vertexai.disableAPIStorage policy is enforced.
  • interactions.create chains onto a queued or in_progress turn, or sets input on requires_continuation.
  • interactions.delete targets a queued or in_progress turn.
  • Use a project that allows API state persistence.
  • Chain only onto final turns. On requires_continuation, pass continuation_token and omit input.
  • Cancel active turns before you delete them.
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")
  • The caller doesn't have roles/aiplatform.user.
  • The caller doesn't have storage.objects.get on gs:// inputs.
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.
  • Retry after the Retry-After header delay with backoff and jitter.
  • Request adjustable quota increases in Deferred tier quotas and limits. Daily throughput limits are fixed.
status="failed"
  • An upstream model or tool failure occurred, or the turn exceeded the 24-hour completion window.
  • The request uses a *-cyber* model, and the project doesn't have allowlist access.
  • Inspect the error field that interactions.get returns, and then submit a new interactions.create request.
  • For Cyber models, confirm allowlist access with your Cloud de Confiance by S3NS account team.

What's next

Explore related guides and reference documentation for asynchronous and stateful Gemini workloads: