Gemini 3.8 Flash HIGH: does maxOutputTokens include thinking tokens?

Gemini API Documentation
1

For gemini-3.8-flash through the Gemini Developer API (not Vertex/Agent Platform or Live API), does setting generationConfig.maxOutputTokens = 8192 enforce a combined ceiling of 8192 tokens for usageMetadata.thoughtsTokenCount + usageMetadata.candidatesTokenCount when thinkingConfig.thinkingLevel = HIGH?

We use the official Node.js SDK @google/genai 2.18.0 and generateContent, with a single text/JSON response and a response schema. There are no attachments, tools, grounding, explicit cache, or thought summaries. candidateCount is intentionally omitted because current documentation marks it unsupported for recent Flash models.

Please clarify:

  1. Whether maxOutputTokens includes raw thinking tokens, or only the visible response, for this exact model and endpoint.
  2. If thinking is separate, the maximum chargeable thinking tokens per request at HIGH and the supported way to bound the combined amount without downgrading HIGH.
  3. Whether a request ending in HTTP 503 or client timeout can accrue billable tokens without returning usageMetadata, and how that usage is identified.
  4. Where the applicable official model/API documentation states this behavior.

Our planned test has at most 4096 input tokens and 8192 output tokens, with one initial generation and only one additional application-level attempt if the first returns HTTP 503. SDK automatic retries are disabled (retryOptions.attempts=1). The conditional estimate is USD 0.067584 for two fully used requests at the Standard prices shown on September 4, 2026. We have not enabled billing to test the budget assumption itself.

The documentation reviewed includes the GenerateContent API reference and the thinking guide. We understand that thinking tokens are billed as output; the question is whether the configurable generation ceiling also includes them for this exact model.

Thank you for any model-specific clarification or official documentation link.

2

Hello @Pax ,

Yes. The maxOutputTokens parameter sets a hard ceiling on the combined total of thinking tokens (usageMetadata.thoughtsTokenCount) and response candidate tokens (usageMetadata.candidatesTokenCount).

You can verify this behavior directly in your environment by running a test call with a low output limit on a reasoning task:

curl "https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent?key=${GEMINI_API_KEY}" \
  -H 'Content-Type: application/json' \
  -X POST \
  -d '{
    "contents": [{
      "parts": [{"text": "Solve this logic puzzle: Three boxes are labeled Apples, Oranges, and Mixed. All labels are incorrect. You pick one fruit from the box labeled Mixed. How do you label all correctly?"}]
    }],
    "generationConfig": {
      "maxOutputTokens": 100,
      "thinkingConfig": {
        "thinkingLevel": "HIGH"
      }
    }
  }'

In the response, you will observe candidates[0].finishReason: "MAX_TOKENS" with empty or truncated candidate text, and generated output tokens bounded by your maxOutputTokens limit.

Failed requests that return a non-200 HTTP status (such as HTTP 503) return no usageMetadata and do not accrue billable output tokens. Output token billing is derived strictly from the token counts reported in the response metadata of completed requests.

3

Thank you, @Sai_Deepika_K. The thinking guide now clarifies that maxOutputTokens includes thinking plus visible output. We kept the limit at 8192 rather than deliberately truncating at 100. Our remaining blocker is that generateContent returns HTTP 503 UNAVAILABLE before we receive usable output. Could you help us identify the right next diagnostic or route this for a project-specific review?

Latest controlled test (September 15, 2026)

  • Gemini Developer API, exact model gemini-3.8-flash, @google/genai 2.18.0, Node.js 24.19.0, Windows.
  • AI Studio shows the project on Free Tier. Before the test, its one-day view showed 0/5 RPM, 0/250,000 TPM and 0/20 RPD. We understand that the dashboard can lag by 15 minutes and does not reserve capacity.
  • models.get succeeds and advertises generateContent and thinking support; we do not interpret that as proof of generation capacity.
  • One text-only task, non-streaming, thinkingLevel MEDIUM, maxOutputTokens 8192, 300-second total timeout, JSON MIME with a seven-field responseJsonSchema. No attachments, tools, URL Context, explicit cache, fallback or model switching. Input was locally estimated at 921 tokens, not remotely measured.
  • We reused the previous HIGH test envelope, changing only the reasoning level and the local idempotency key. This is a later observation, not a simultaneous A/B experiment. Previous HIGH and MEDIUM tasks on separate days also failed.
  • UTC window: 2026-09-15 22:07:26.985 to 22:07:51.855. First call: 503 UNAVAILABLE. After 23.889 seconds, the only application-level retry: 503 UNAVAILABLE. Total elapsed: 24.870 seconds. SDK automatic retries were disabled with retryOptions.attempts=1. We stopped there.
  • No usable text, usageMetadata, modelVersion, request ID or Retry-After was observable through this SDK error path. This does not mean those headers were absent at the HTTP layer.

We read the pinned 429/503 guidance and the related 3.7/Priority discussion. We are not assuming that a different model or paid workload has the same cause as ours.

Remaining questions

  1. How can we distinguish ordinary Free Tier capacity shedding from a project-specific access or backend issue when every sampled generation fails but models.get works and displayed quota is unused?
  2. Is there a known issue for this exact model with non-streaming generateContent, MEDIUM/HIGH and responseJsonSchema? Which single request variable would you recommend testing next to isolate the cause?
  3. Is this pattern across several days expected for Free Tier, and is there an applicable incident/status entry or recovery guidance beyond generic retry advice?
  4. What bounded retry spacing do you recommend for this case, and which safe request identifier or header should we collect for support if the SDK does not expose it? We want to avoid retry loops.
  5. What minimum information is needed for a project-specific review, and which official private channel should receive it? We will not post credentials or private project identifiers publicly.
  6. Could you link the generateContent billing documentation supporting the statement that non-200 requests do not accrue billable output tokens? Please distinguish a server-returned 503 from a client timeout/disconnection after remote work may have started. The API-errors link currently describes Interactions API and I could not find that billing guarantee there.
  7. Would moving this exact model/workload to a paid tier materially change capacity availability, or only quota/priority? Is there a documented guarantee or evidence for that distinction? Billing remains disabled; we are not requesting an upgrade.
  8. Please confirm that the combined maxOutputTokens ceiling also applies with responseJsonSchema on this endpoint at MEDIUM/HIGH. The general ceiling is now clear; we have not been able to observe it in a successful generation.

Thank you. A concrete next diagnostic or the correct private escalation route would help us move forward without repeatedly consuming requests.

4

Following up on the answer above that maxOutputTokens is a hard ceiling on thinking plus response tokens. On gemini-3.8-flash and gemini-3.7-flash we regularly see the combined total land at almost exactly 2x the cap, on both the Gemini API and Vertex AI

Minimal repro against the Gemini API (plain generateContent, no tools, no system instruction):

curl -s https://generativelanguage.googleapis.com/v1beta/models/gemini-3.8-flash:generateContent \
  -H "x-goog-api-key: $GEMINI_API_KEY" -H "Content-Type: application/json" \
  -d '{"contents":[{"role":"user","parts":[{"text":"Find all integer solutions (x, y) with |x|,|y| <= 60 to x^3 - 3xy^2 + y^3 = 2891. Check candidates carefully, then submit the final list with the tool."}]}],
       "generationConfig":{"maxOutputTokens":512,"temperature":0,"topP":0,
                           "thinkingConfig":{"includeThoughts":true,"thinkingLevel":"low"}}}' \
  | jq '{finish: .candidates[0].finishReason, thoughts: .usageMetadata.thoughtsTokenCount, response: .usageMetadata.candidatesTokenCount}'

Five runs per model on 2026-09-24, maxOutputTokens 512, thinkingLevel low (totals are thoughtsTokenCount plus candidatesTokenCount):

model runs over 512 totals
gemini-3.8-flash 5 of 5 999, 999, 1001, 1003, 997
gemini-3.7-flash 2 of 5 1005, 999, 506, 508, 508

The same request through Vertex AI shows the same pattern, for example 6 of 6 runs over on gemini-3.8-flash with totals of 997 to 1001. In production traffic with maxOutputTokens 16384 and thinkingLevel low we logged totals up to 32,108 tokens, 31,458 of them thoughts, and none of those calls finished with MAX_TOKENS

Some details that may help narrow it down. The overshoot is always in thoughtsTokenCount and never in visible output. Totals are bimodal, either close to the cap or close to 2x, with one run at 549. finishReason is not a reliable signal: overshooting runs came back as MAX_TOKENS, STOP and MALFORMED_FUNCTION_CALL, the last one with no tools in the request. Spelling the field maxOutputTokens or max_output_tokens makes no difference, and neither does includeThoughts true or false

Is this expected? If it is, could the docs say the effective ceiling can reach roughly 2x maxOutputTokens when thinking is on, so callers can size timeouts and budgets accordingly