List Audio History
Overview
List historical audio tasks for the authenticated account. Use this endpoint to build media libraries or resume polling tasks created earlier.
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/audio/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/audio/history?page=1&limit=20Response Example
{
"success": true,
"data": {
"items": [
{
"task_id": "aud_01HQ9MB2J3RWB1V8Y5B9H8M2QK",
"model": "V5",
"source": "suno",
"created_at": "2026-03-12T09:40:00.000Z",
"status": "completed",
"audio_url": "https://cdn.apimall.ai/generated/audio-01.mp3",
"image_url": "https://cdn.apimall.ai/generated/audio-cover-01.webp",
"credits_used": 12,
"credits_refunded": 0,
"completed_at": "2026-03-12T09:41:30.000Z"
}
],
"page": 1,
"limit": 20
},
"request_id": "req_01HQ9M7J7X9P7Y8T6W5V4U3S2R"
}cURL Example
curl --request GET 'https://gateway.apimall.ai/api/v1/audio/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/audio/history?${params.toString()}`, {
headers: {
Authorization: `Bearer ${API_KEY}`,
},
});
if (!response.ok) {
throw new Error(`List history failed: ${response.status} ${response.statusText}`);
}
const data = await response.json();
for (const item of data.data?.items || []) {
console.log({
taskId: item.task_id,
status: item.status,
audioUrl: item.audio_url,
});
}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[].audio_url | string | Hosted audio URL for a historical audio 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 |