Exports

Get testimonials out in bulk: a spreadsheet for your team, data for your own systems, or the media files themselves.

How an export runs

An export is a job, not a request: a hundred videos do not fit in one HTTP response.

1. Optionally, ask what it would contain. Nothing is counted against your plan.

curl -H "Authorization: Bearer $AKTEORA_API_KEY" -H 'content-type: application/json' \
  -d '{ "format": "csv", "filters": { "brand_id": "brd_…", "is_approved": true } }' \
  https://api.akteora.com/v1/exports/preview

The answer gives:

• submission_count;
• media_file_count, the recordings a ZIP would hold;
• your plan's limits;
• blocked, which is null when the export can run. Otherwise it says why, in detail, names the limit in the way, and gives the plan that raises it (upgrade_to).

2. Start it.

curl -H "Authorization: Bearer $AKTEORA_API_KEY" -H 'content-type: application/json' \
  -d '{ "format": "csv", "filters": { "brand_id": "brd_…", "is_approved": true } }' \
  https://api.akteora.com/v1/exports

202 Accepted, with { "export_id": "…" }.

3. Wait for it. Fetch GET /v1/exports/{export_id}:

• status moves from queued to running to succeeded, or to failed, in which case error_message says why;
• progress.processed of progress.total counts the testimonials written so far.

A ZIP bundle, or a list of more than 100 testimonials, also emails the person who started it when it is ready.

4. Download it. Once succeeded:

• download_url is a signed link, valid for 24 hours from that response. Fetch the export again for a fresh one.
• The file itself is deleted 7 days after it finished (expires_at), and status becomes expired.

Filters

The same meanings as the testimonial list's filters. Testimonials the respondent has not sent yet are never exported.

The CSV

UTF-8 with a byte-order mark, so Excel reads accents and non-Latin scripts correctly, and lines end in CRLF. One row per testimonial, in these columns:

public_media_url and public_poster_url are the same permanent addresses as public_media. They are set only for testimonials that are published (approved, public, processed, not rejected), and empty for everything else. They are safe to store, paste into a CMS, or hand to an agency. They are never signed links, because a spreadsheet outlives any signature. To get files for testimonials that are not published, export a zip.

Formula safety. Every cell was typed by someone on the internet, and Excel runs a cell that begins with =. A cell beginning with =, +, -, @, a tab or a carriage return is therefore prefixed with '. The JSON export keeps the exact characters.

The JSON

{
  "export_id": "…",
  "exported_at": "2026-09-13T10:00:00.000Z",
  "data": [
    {
      "id": "sub_…",
      "brand": { "id": "brd_…", "name": "Northwind" },
      "kind": "video",
      "respondent": { "name": "Maria López", "email": "…", "title": "…", "company": "…", "country": "ES" },
      "text": "…",
      "text_source": "original",
      "original_text": "…",
      "transcript": {
        "text": "Great team.",
        "language": "en",
        "words": [{ "word": "Great", "start_ms": 0, "end_ms": 300, "confidence": 0.9 }],
        "segments": [{ "text": "Great team.", "start_ms": 0, "end_ms": 700 }]
      },
      "tags": [{ "name": "case study", "source": "operator" }],
      "is_approved": true,
      "is_public": true,
      "public_media_url": "https://cdn.akteora.com/m/7kq2m9xwzr4tn8vbh3jp/video.mp4",
      "public_poster_url": "https://cdn.akteora.com/m/7kq2m9xwzr4tn8vbh3jp/poster.jpg",
      "consent": { "consent_text": "…", "consent_version": "v1", "agreed_at": "…" }
    }
  ]
}

It has the CSV's information and more:

• the consent the respondent agreed to, word for word;
• the text as originally typed;
• word timings and segments, for building captions.

The example above is abridged.

The ZIP bundle

A manifest.csv (the CSV above, plus a file column), and each testimonial's processed recording under media/, named after the respondent and the testimonial's id: media/maria-lopez-sub_….mp4, or .m4a for audio. It is streamed as it is built, so size is limited by your plan, not by memory.

Limits

Each plan allows a number of exports a month, testimonials per export, and recordings per ZIP. An export over a limit is refused before it starts, with 402 and a problem of type plan_limit_exceeded. Its limit member names:

• which limit was exceeded;
• your plan's allowance;
• what you asked for;
• the plan that allows it.

A refused export does not count against the month.