> For the complete documentation index, see [llms.txt](https://developers.gamma.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.gamma.app/agent-gamma-5/get-agent-generation-status.md).

# GET /agent/generations/{generationId}

Poll an agent generation until status is completed or failed.

Poll an agent generation job until `status` is `completed` or `failed`: a completed response carries the gamma's id and URL, the agent's `result.summary`, and any `exportUrl`; a failed one carries `error`; both report `credits.deducted` / `credits.remaining` when the lookups succeed. While the job is still `pending`, optional `progress` reports card counts and an estimated completion percentage once the agent starts building cards. Agent generation ids are prefixed with `gen_`.

## Get agent generation status

> Retrieves the current status of an agent generation. Poll this endpoint until \`status\` is "completed" or "failed". The \`gamma\` object can appear on a pending generation once the document has been created.

```json
{"openapi":"3.0.0","info":{"title":"Gamma Public API","version":"1.0"},"tags":[{"name":"public-api","description":"Public API endpoints for external integrations"}],"servers":[{"url":"https://public-api.gamma.app","description":"Production"}],"security":[{"api-key":[]}],"components":{"securitySchemes":{"api-key":{"type":"apiKey","in":"header","name":"X-API-KEY","description":"API key for authentication"}},"schemas":{"PendingAgentGenerationResponse":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique id for the generation job, prefixed `gen_`.","pattern":"^gen_[A-Za-z0-9]+$"},"status":{"type":"string","enum":["pending"]},"gamma":{"description":"Can appear once the document has been created.","allOf":[{"$ref":"#/components/schemas/AgentGenerationGamma"}]},"progress":{"description":"Can appear once the agent starts building cards.","allOf":[{"$ref":"#/components/schemas/AgentGenerationProgress"}]},"warnings":{"description":"Always empty while pending. Request-level warnings are returned on create\nand again on the completed response.","type":"array","items":{"$ref":"#/components/schemas/AgentGenerationWarning"}},"updatedTime":{"type":"string","description":"ISO-8601 timestamp of the last state change."}},"required":["generationId","status","warnings","updatedTime"]},"AgentGenerationGamma":{"type":"object","properties":{"gammaId":{"type":"string","description":"File id of the generated gamma."},"gammaUrl":{"type":"string","description":"Editor URL of the generated gamma."}},"required":["gammaId","gammaUrl"]},"AgentGenerationProgress":{"type":"object","properties":{"stages":{"$ref":"#/components/schemas/AgentGenerationProgressStages"},"done":{"type":"number","description":"Cards finished."},"total":{"type":"number","description":"Cards in the gamma."},"percent":{"type":"number","description":"Estimated completion, 0 to 99. Never decreases within one generation\nattempt, but can restart lower if the agent retries the generation;\n`completed` is still the only 100."}},"required":["stages","done","total","percent"]},"AgentGenerationProgressStages":{"type":"object","properties":{"queued":{"type":"number"},"writing":{"type":"number"},"imaging":{"type":"number"},"checking":{"type":"number"},"polishing":{"type":"number"},"done":{"type":"number"},"failed":{"type":"number"}}},"AgentGenerationWarning":{"type":"object","properties":{"code":{"type":"string","description":"Machine-readable warning code.","enum":["email_full_access_members_only","email_invites_failed","export_failed","external_access_failed","folder_placement_failed","ignored_email_options","ignored_email_recipients","ignored_external_access","ignored_folder_id","ignored_workspace_access","workspace_access_failed"]},"message":{"type":"string","description":"Human-readable explanation, suitable for display."}},"required":["code","message"]},"CompletedAgentGenerationResponse":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique id for the generation job, prefixed `gen_`.","pattern":"^gen_[A-Za-z0-9]+$"},"status":{"type":"string","enum":["completed"]},"gamma":{"$ref":"#/components/schemas/AgentGenerationGamma"},"result":{"$ref":"#/components/schemas/AgentGenerationResult"},"exportUrl":{"type":"string","description":"Download URL for the exported artifact. Present only when `exportAs`\nwas requested and the export succeeded; a failed export appears as an\n`export_failed` warning instead."},"warnings":{"description":"Warnings accumulated during the run. Empty array when there are none.","type":"array","items":{"$ref":"#/components/schemas/AgentGenerationWarning"}},"updatedTime":{"type":"string","description":"ISO-8601 timestamp of the last state change."},"credits":{"description":"Credit accounting for this job. Present on every completed or failed\nresponse; each member is best-effort and omitted when unknown.","allOf":[{"$ref":"#/components/schemas/AgentCreditsResponse"}]}},"required":["generationId","status","gamma","result","warnings","updatedTime","credits"]},"AgentGenerationResult":{"type":"object","properties":{"summary":{"type":"string","description":"Agent-written summary of what was generated."}},"required":["summary"]},"AgentCreditsResponse":{"type":"object","properties":{"deducted":{"type":"number","description":"Credits recorded as debited from your balance for this job so far: the\nagent's model and tool spend settled from its ledger plus image generation\ncharged as it ran. Actual amounts removed, not list prices — spend that\ncould not be charged because the balance was empty is not included. It can\nstill grow if a late settlement lands after completion, and accounting is\nbest-effort: a failed record write can leave it low, and `0` means no\ncharge was recorded. Omitted when the job's charge record cannot be\nlooked up at all."},"remaining":{"type":"number","description":"Credits currently available to the authenticated user in this workspace,\nread when this status was served. Not what this job cost: other jobs,\npurchases and refills move it between polls. Omitted if the balance\nlookup fails."}}},"FailedAgentGenerationResponse":{"type":"object","properties":{"generationId":{"type":"string","description":"Unique id for the generation job, prefixed `gen_`.","pattern":"^gen_[A-Za-z0-9]+$"},"status":{"type":"string","enum":["failed"]},"gamma":{"description":"Present when the document was created before the failure.","allOf":[{"$ref":"#/components/schemas/AgentGenerationGamma"}]},"error":{"$ref":"#/components/schemas/AgentGenerationError"},"warnings":{"description":"Usually empty: warnings returned on create are not guaranteed to be\nrepeated here, so keep them from the create response.","type":"array","items":{"$ref":"#/components/schemas/AgentGenerationWarning"}},"updatedTime":{"type":"string","description":"ISO-8601 timestamp of the last state change."},"credits":{"description":"Credit accounting for this job. Present on every completed or failed\nresponse; each member is best-effort and omitted when unknown.","allOf":[{"$ref":"#/components/schemas/AgentCreditsResponse"}]}},"required":["generationId","status","error","warnings","updatedTime","credits"]},"AgentGenerationError":{"type":"object","properties":{"reason":{"type":"string","description":"Machine-readable failure reason.","enum":["access_revoked","generation_failed","insufficient_credits","timeout","unavailable"]},"message":{"type":"string","description":"Human-readable explanation."},"statusCode":{"type":"number","description":"HTTP-style status code for the failure reason."}},"required":["reason","message","statusCode"]}}},"paths":{"/v1.0/agent/generations/{generationId}":{"get":{"description":"Retrieves the current status of an agent generation. Poll this endpoint until `status` is \"completed\" or \"failed\". The `gamma` object can appear on a pending generation once the document has been created.","operationId":"getAgentGenerationStatus","parameters":[{"name":"generationId","required":true,"in":"path","description":"The generation id returned by `POST /v1.0/agent/generations`.\nAgent generation ids are prefixed `gen_`.","schema":{"maxLength":128,"pattern":"^gen_[A-Za-z0-9]+$","type":"string"}}],"responses":{"200":{"description":"Generation status retrieved successfully","content":{"application/json":{"schema":{"oneOf":[{"$ref":"#/components/schemas/PendingAgentGenerationResponse"},{"$ref":"#/components/schemas/CompletedAgentGenerationResponse"},{"$ref":"#/components/schemas/FailedAgentGenerationResponse"}]}}}},"400":{"description":"Invalid request parameters"},"401":{"description":"Invalid or missing API key"},"404":{"description":"Generation not found"},"429":{"description":"Rate limit exceeded"}},"summary":"Get agent generation status","tags":["public-api"]}}}}
```

{% hint style="info" %}
The `gamma` object can appear while the job is still `pending`, once the document has been created. Optional `progress` (`done`, `total`, `percent`, and per-stage counts in `stages`) can appear once card building starts; `percent` runs from 0 to 99 and only `completed` means 100%. Keep polling until `status` is `completed` or `failed`. See [Poll for results](/guides/async-patterns-and-polling.md) for pacing and rate limit headers.
{% endhint %}

## Related

* [POST /agent/generations](/agent-gamma-5/create-agent-generation.md) to start a new agent generation
* [Poll for results](/guides/async-patterns-and-polling.md) for complete polling implementations
* [GET /gammas/{gammaId}](/management/get-gamma.md) for metadata after you have a `gammaId`


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://developers.gamma.app/agent-gamma-5/get-agent-generation-status.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.