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

# Suno API Async Workflow

> Learn how to handle Suno API jobs with polling, webhooks, fetch endpoints, retries, and production-safe async workflow patterns on TTAPI.

# Suno API Async Workflow

Most production **Suno API** integrations are asynchronous. Your app submits a job, receives a `jobId`, and then waits for the final result through polling or a webhook.

This guide explains how to structure that workflow cleanly on TTAPI. For the full endpoint map, see the [Suno API docs overview](/api/en/suno).

## When the async model matters

Use an async-ready integration whenever you:

* Generate full songs or longer audio assets
* Upload reference audio before downstream processing
* Need reliable background processing in a backend or queue worker
* Want to avoid blocking a user request until media is complete

## The core pattern

1. Submit a job through an endpoint such as [Suno Music](/api/en/suno/suno_music), [Upload](/api/en/suno/suno_upload), [Cover](/api/en/suno/suno_cover), or [Extend](/api/en/suno/suno_extend).
2. Store the returned `jobId` in your database or queue.
3. Retrieve the final output through [Suno Fetch V2](/api/en/suno/suno_fetch_v2) or a `hookUrl`.
4. Update your application state only after the job reaches a terminal result.

## Polling vs webhook

| Approach                                       | Best when                                                        | Notes                                |
| :--------------------------------------------- | :--------------------------------------------------------------- | :----------------------------------- |
| [Fetch V2](/api/en/suno/suno_fetch_v2) polling | You want a simple implementation or your client controls refresh | Easier to debug and replay           |
| `hookUrl` callback                             | You already run a public backend and want push-based updates     | Better for reducing repeated polling |

## When to prefer Fetch V2

Polling is usually the best starting point when:

* You are building the first version of the integration
* You want to inspect job transitions in logs
* You need to manually retry failed fetches
* Your app already has a worker or scheduled job system

## When to prefer webhooks

Callbacks are a better fit when:

* You want immediate background completion updates
* You are processing many jobs every day
* You want to reduce repeated fetch traffic
* Your backend can expose a stable public endpoint

## Recommended implementation details

* Persist `jobId`, request type, and submission time together
* Treat job fetching as idempotent so retries are safe
* Keep a clear mapping between endpoint type and expected result payload
* Log webhook deliveries and fetch responses for debugging
* Keep a fallback path that lets you query [Fetch V2](/api/en/suno/suno_fetch_v2) even if a webhook fails

## Common failure patterns

* The webhook URL is not publicly reachable
* The application discards `jobId` too early
* The frontend expects final media in the submit response
* The app mixes deprecated [Fetch](/api/en/suno/suno_fetch) behavior with [Fetch V2](/api/en/suno/suno_fetch_v2)
* The workflow has no retry or timeout logic for long-running jobs

## Which pages to read next

* [Suno API docs overview](/api/en/suno)
* [Suno Fetch V2 API](/api/en/suno/suno_fetch_v2)
* [Suno Upload API](/api/en/suno/suno_upload)
* [Suno Music API](/api/en/suno/suno_music)
* [Gateway & Auth](/grids/en/development/authentication)