EsferaDevelopers
Log inGet access →

Retention ​

Esfera keeps the output of a conversion made through the API for 72 hours after the job finishes, then removes it. This page explains when the clock starts, how you are warned, how the download behaves, and what you see once the file is gone. Download the file and keep your own copy. The API is a conversion service, not storage.

The window ​

  • 72 hours from the moment the conversion reaches a terminal status, ready or error. Both start the clock, because a failed job's uploaded master must also leave storage.
  • The conversion's expiresAt is that moment plus 72 hours. It is null until the conversion is terminal. GET /v1/usage reports the window as limits.retentionHours.
  • When the window closes, the server removes the master and the output. The conversion record is soft-deleted. The minutes a finished conversion used stay counted against your allowance: expiry does not refund them, and neither does deleting a conversion yourself.
  • No call extends the window. To keep a file longer, download it.

The warning: conversion.expiring ​

About 24 hours before expiresAt, each conversion that has not yet been warned gets one conversion.expiring event to your webhook endpoints. It is not sent at a precise moment, so treat it as roughly a day's notice.

  • It is sent once per conversion.
  • The payload is the conversion as it stands, with status of ready or, for a failed job, error. The payload's updatedAt is the time the warning was sent. See Events and payload.
  • It is not sent for conversions that have no expiresAt, which means conversions created in the Esfera web app.
  • If you have no endpoint registered when it fires, it is not held for you.

If your pipeline downloads each file as soon as conversion.completed arrives, you never need this event. Use it as a safety net for the files your pipeline did not collect.

Downloading ​

GET /v1/conversions/{id}/output streams the file while the conversion is ready and unexpired. It is served through the API, not as a redirect to a storage URL, so it needs your API key like any other call. You can download as often as you like inside the window.

BehaviourDetail
Success200 with the whole file, or 206 for a range
Content-Typeaudio/iamf
Content-Dispositionattachment; filename="<name>.iamf", built from the conversion's name with unsafe characters replaced by _
Accept-Rangesbytes
ETagPresent
Cache-Controlprivate, max-age=60
Content-LengthThe size of the response body

Range requests ​

Send Range: bytes=start-end or Range: bytes=start- to fetch part of the file, for example to resume an interrupted download. The answer is 206 Partial Content with Content-Range: bytes start-end/total. Only a single range with a starting offset is understood. A suffix range such as bytes=-500 is not, and the whole file comes back with 200.

bash
# Resume a download from byte 104857600
curl -H "Authorization: Bearer $ESFERA_API_KEY" -H "Range: bytes=104857600-" \
  "https://api.esfera.audio/v1/conversions/$ID/output" -o master.iamf.part

The SDK's download() streams the body without a request timeout, since a large file can legitimately take minutes. It does not resume for you.

After expiry ​

Expired files are purged within a few hours of expiresAt. So expiresAt is the time the file becomes eligible for removal, and it may stay downloadable for a short while after it. Do not rely on that.

Once the purge has run:

  • GET /v1/conversions/{id}/output answers 404 not-found with the detail "No output available for this conversion".
  • GET /v1/conversions/{id} answers 404 not-found too, because the record is gone from the API. It no longer appears in GET /v1/conversions.
  • In the short interval where the record still exists but the stored file has gone, the output call answers 404 with "Output is no longer stored".

Treat any 404 from the output call on a conversion you created as "expired or deleted", and make a new conversion if you still need the file.

developers.esfera.audio · the Esfera Converter API, SDK and CLI