Skip to main content
Enterprise API

Data retention and deletion

Control how long request inputs and outputs are stored, and delete a request on demand.

Every generation request stores the files you send and the files it produces. You decide how long they are kept: seven days by default, or as little as one hour. You can also delete a finished request at any time.

#Retention periods

Source Range Applies to
Default 7 days Every request
Account retention 1 hour to 7 days Every new request of the account: a personal account or an organization. Configured by Higgsfield on request.
Hf-Expires-After header 3600 seconds to your account retention One request; it can only shorten the period

Retention counts from the moment the request finishes (completed, failed, nsfw or canceled), so a long generation does not eat into the time you have to download its result. The period is fixed when the request is created: changing the account retention later does not affect existing requests.

#Set retention for a request

Send Hf-Expires-After with the number of seconds to keep the request after it finishes:

bash
curl --request POST \
  --url https://api.higgsfield.ai/xai/grok-imagine-image-2.0 \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}" \
  --header "Content-Type: application/json" \
  --header "Hf-Expires-After: 3600" \
  --data '{
    "prompt": "Editorial portrait in soft daylight"
  }'

The response confirms the period that applies:

json
{
  "status": "queued",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "status_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/status",
  "cancel_url": "https://api.higgsfield.ai/requests/d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff/cancel",
  "expires_after": 3600
}
  • A value below 3600 or above your account retention returns 422 Unprocessable Entity.
  • The header is part of the Idempotency-Key fingerprint: retry with the same value.
  • The header applies to generation requests for the models in the Model API reference.

#When data expires

Once a request finishes, the status response and the webhook include expires_at, the time after which its data is deleted:

json
{
  "status": "completed",
  "request_id": "d7e6c0f3-6699-4f6c-bb45-2ad7fd9158ff",
  "expires_at": "2026-10-24T13:05:12.481Z",
  "images": [
    { "url": "https://cdn.example.com/image-1.jpg" }
  ]
}

Download the output before expires_at. After it, output URLs stop working. The status endpoint keeps returning the request with its status, but the files are gone.

Warning

With retention shorter than the webhook retry window, a delivery to an endpoint that is down for longer than the retention period is not retried after the data is deleted. Keep polling the status endpoint as a fallback.

#Delete a request now

Delete a finished request's data immediately, regardless of its retention:

bash
curl --request DELETE \
  --url "https://api.higgsfield.ai/requests/${REQUEST_ID}" \
  --header "Authorization: Key ${HF_API_KEY_ID}:${HF_API_KEY_SECRET}"
Status Meaning
200 OK The data was deleted. Repeating the call returns the same response.
404 Not Found The request does not exist or belongs to another account.
409 Conflict The request is still queued or in_progress. Cancel it or wait until it finishes.
503 Service Unavailable Deletion is temporarily unavailable. Retry later with backoff.

#What is deleted

When a request expires with retention shorter than seven days, or when you delete it:

Deleted Kept
Output files: images, videos, audio and other artifacts Request ID, model, status and timestamps
Input files Higgsfield stored for the request Cost and billing records
The prompt and other request parameters
The webhook URL and its secret

With the default seven-day retention, the request's files are deleted after seven days; the prompt and parameters stay with the request record. Use a shorter retention or DELETE to remove them too.

Billing records stay, so usage reports and invoices are not affected by deletion.

Files you upload with file uploads, and copies of inputs that Higgsfield prepares for reuse across requests, are stored independently of a single request and are deleted within seven days. Requests processed by third-party model providers are also subject to the provider's own data policy.

Was this page helpful?
Navigation