> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elumenta.ru/llms.txt
> Use this file to discover all available pages before exploring further.

# Generation History

> Retrieve past generations and check status of async jobs

## List Generation History

Returns a paginated list of your past generations.

### Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number.
</ParamField>

<ParamField query="limit" type="integer" default="20">
  Items per page. Max `100`.
</ParamField>

<ParamField query="type" type="string">
  Filter by generation type: `text`, `image`, `video`, `tts`, `stt`, `audio`, `tool`
</ParamField>

<ParamField query="model" type="string">
  Filter by model slug (e.g. `gpt-5`, `dall-e-3`).
</ParamField>

<ParamField query="status" type="string">
  Filter by status: `completed`, `pending`, `failed`
</ParamField>

### Request

```bash theme={null}
curl "https://elumenta.ru/api/v2/user/history?type=image&limit=10" \
  -H "Authorization: Bearer nb_YOUR_API_KEY"
```

### Response

```json theme={null}
{
  "items": [
    {
      "id": "gen_01j9x2img789",
      "type": "image",
      "model": "flux-1.1-pro",
      "status": "completed",
      "prompt": "Portrait of a CEO in a modern office",
      "url": "https://storage.elumenta.ru/generations/gen_01j9x2img789.webp",
      "tokens_used": 8,
      "created_at": "2026-03-08T12:02:30Z"
    },
    {
      "id": "gen_01j9x2img788",
      "type": "image",
      "model": "dall-e-3",
      "status": "completed",
      "prompt": "Minimalist product shot, white background",
      "url": "https://storage.elumenta.ru/generations/gen_01j9x2img788.webp",
      "tokens_used": 7,
      "created_at": "2026-03-08T11:50:00Z"
    }
  ],
  "total": 142,
  "page": 1,
  "limit": 10,
  "pages": 15
}
```

***

## Check Generation Status

<api>GET /api/v2/generate/status/{generation_id}</api>

Poll the status of an async generation (video, slower image models).

### Path Parameters

<ParamField path="generation_id" type="string" required>
  The generation ID returned from the initial request.
</ParamField>

### Request

```bash theme={null}
curl "https://elumenta.ru/api/v2/generate/status/gen_01j9x2vid001" \
  -H "Authorization: Bearer nb_YOUR_API_KEY"
```

### Response: Pending

```json theme={null}
{
  "id": "gen_01j9x2vid001",
  "status": "pending",
  "model": "kling-v2.1-pro",
  "progress": 45,
  "eta_seconds": 32,
  "created_at": "2026-03-08T12:05:00Z"
}
```

### Response: Completed

```json theme={null}
{
  "id": "gen_01j9x2vid001",
  "status": "completed",
  "model": "kling-v2.1-pro",
  "url": "https://storage.elumenta.ru/generations/gen_01j9x2vid001.mp4",
  "duration": 5,
  "width": 1920,
  "height": 1080,
  "tokens_used": 60,
  "balance_remaining": 229,
  "created_at": "2026-03-08T12:05:00Z",
  "completed_at": "2026-03-08T12:06:02Z"
}
```

### Response: Failed

```json theme={null}
{
  "id": "gen_01j9x2vid002",
  "status": "failed",
  "model": "kling-v2.1-pro",
  "error": "Provider error: content policy violation",
  "tokens_used": 0,
  "created_at": "2026-03-08T12:10:00Z"
}
```

<Note>
  When a generation fails, **no tokens are charged**.
</Note>

## Recommended Polling Strategy

```python theme={null}
import requests
import time

def wait_for_generation(gen_id: str, api_key: str, timeout: int = 300):
    """Poll until generation completes or times out."""
    headers = {"Authorization": f"Bearer {api_key}"}
    deadline = time.time() + timeout
    
    while time.time() < deadline:
        res = requests.get(
            f"https://elumenta.ru/api/v2/generate/status/{gen_id}",
            headers=headers
        )
        data = res.json()
        
        if data["status"] == "completed":
            return data
        elif data["status"] == "failed":
            raise Exception(f"Generation failed: {data.get('error')}")
        
        # Use eta_seconds hint if available
        wait = min(data.get("eta_seconds", 10), 10)
        time.sleep(wait)
    
    raise TimeoutError(f"Generation {gen_id} timed out after {timeout}s")
```

## Storage Retention

Generated files are stored based on your plan:

| Plan    | Retention |
| ------- | --------- |
| Starter | 7 days    |
| Basic   | 30 days   |
| Pro     | 90 days   |
| VIP     | 90 days   |
| Elite   | Unlimited |