List Image History
Overview
List historical image tasks for the authenticated account. Use this endpoint to build task history UIs or recover previous task IDs without storing your own index.
Authentication
All API requests require a Bearer token in the request header.
Authorization: Bearer YOUR_API_KEYCreate and manage API keys from API Keys or use https://www.apimall.ai/api-keys.
Request
API Information
- URL:
GET https://gateway.apimall.ai/api/v1/images/history
Query Parameters
| Parameter | Type | Required | Description |
|---|---|---|---|
page | integer | Optional | Page number for paginated results. Default: |
limit | integer | Optional | Number of records to return per page. Default: Range: 1 - 50 |
Request Example
GET https://gateway.apimall.ai/api/v1/images/history?page=1&limit=20Response Example
{
"success": true,
"data": {
"items": [
{
"task_id": "img_01HQ9M7XJQ7PZ3GQ9F6C5W3N2M",
"model": "nano-banana",
"source": "gempix2",
"created_at": "2026-03-12T09:30:00.000Z",
"status": "completed",
"image_url": "https://cdn.apimall.ai/generated/image-01.webp",
"credits_used": 8,
"credits_refunded": 0,
"completed_at": "2026-03-12T09:31:06.000Z"
}
],
"page": 1,
"limit": 20
},
"request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}cURL Example
curl --request GET 'https://gateway.apimall.ai/api/v1/images/history?page=1&limit=20' \
--header 'Authorization: Bearer YOUR_API_KEY'JavaScript Example
const API_KEY = process.env.APIMALL_API_KEY;
const params = new URLSearchParams({
"page": "1",
"limit": "20",
});
const response = await fetch(`https://gateway.apimall.ai/api/v1/images/history?${params.toString()}`, {
headers: {
Authorization: `Bearer ${API_KEY}`,
},
});
if (!response.ok) {
throw new Error(`Request failed: ${response.status} ${response.statusText}`);
}
const data = await response.json();
console.log(data);Response Parameters
| Parameter | Type | Description |
|---|---|---|
success | boolean | Whether the request completed successfully. |
data.items | array | List of items returned for the current page. |
data.items[].task_id | string | Task identifier for a historical generation record. |
data.items[].model | string | Model used for the historical task. |
data.items[].source | string | Internal source/provider family that fulfilled the historical task. |
data.items[].created_at | string | Creation timestamp for the historical task. |
data.items[].status | string | Status value for the historical resource or task. |
data.items[].image_url | string | Hosted image URL for a historical image or audio-cover result. |
data.items[].credits_used | integer | Credits charged for the historical task. |
data.items[].credits_refunded | integer | Credits refunded for the historical task, if any. |
data.items[].completed_at | string | Completion timestamp for the historical task when available. |
data.page | integer | Current page number in the paginated response. |
data.limit | integer | Maximum number of items returned per page. |
request_id | string | Request identifier for debugging and support. |
Error Response Example
{
"success": false,
"error": {
"code": "unauthorized",
"message": "Unauthorized"
},
"request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}Integration Notes
- Store your API key on the server side only.
- Use the paginated history response to recover prior task IDs and recent outputs.
- Increase `page` rather than `limit` when scanning long task histories.
Error Codes
Common Error Codes
| Status Code | Description |
|---|---|
| 200 | Request successful |
| 401 | API key required or invalid API key |
| 403 | API access not approved or request made on a non-gateway host |
| 404 | Resource not found |
| 429 | Rate limit exceeded |
| 500 | Internal server error |