---
title: "Poll one generation task"
method: GET
path: "/api/funko/task"
tags: ["funko", "browser-session"]
---

# Poll one generation task

`GET /api/funko/task`

## Request

- Base URL: `https://www.immersivecommons.com`
- URL: `https://www.immersivecommons.com/api/funko/task`
- Auth: API key in cookie `__session`

Clerk-session only, and gated on a runId this caller owns. A FAILED generation is a 200 carrying an `error` field, NOT an HTTP error - an HTTP error here means the poll itself could not be performed, which is the distinction a client absorbing transient network failures depends on. Polling is not itself billed but is gated anyway, because an open poll would leak whether an arbitrary task id exists and what it produced.

## Query parameters

- `runId` string, required
- `kind` 'image' | 'mesh', required
- `id` string, required

## Response `200`

The task's current status. `status: "FAILED"` is still a 200.

- FunkoTaskResponse
  - `ok` boolean, required
  - `status` string, required: PENDING | IN_PROGRESS | SUCCEEDED | FAILED.
  - `progress` integer, required: 0..100. Forced to 100 on SUCCEEDED.
  - `imageUrls` string[]: Image tasks only.
  - `modelUrl` string: Mesh tasks only.
  - `error` string: Present when status is FAILED. A failed generation is still HTTP 200.

## Other responses

- `400`: Missing/invalid `kind` or `id`.
- `401`: Not signed in.
- `403`: The runId is unknown, expired, finished, or belongs to someone else - deliberately one indistinguishable refusal.
- `429`: Upstream rate limit.
- `502`: Upstream generation service failed.

---

[API](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api.md) · [All operations](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/llms.txt) · [OpenAPI document](https://skmtc.dev/immersivecommons/apis/immersive-commons-agent-rest-api/revisions/be67c1f67c27?raw)