Skip to content
API docs
Sign inOpen app

Exports

Start a CSV export

POST/v1/exports

Start exporting a form's responses as one CSV file of any size, prepared in the background, with the same filters and sort as GET /v1/submissions. Poll GET /v1/exports/{exportId} until status is ready, then call POST /v1/exports/{exportId}/download within a day. After a day the file is deleted. Asking again for the same export while it runs gives you that one back. You can start 20 an hour, and more answer 429. See Export columns.

Body

JSON, with Content-Type: application/json.

  • formIdstringrequired

    The form whose responses to export.

  • statusenum

    complete for responses where the person finished the form, partial for the rest. Use state to tell people still filling it in from people who left.

    One of "partial", "complete"

  • stateenum

    started for people still filling in the form, left for people who left without finishing, finished for people who finished. See Response states.

    One of "started", "left", "finished"

  • endingIdstring

    Only finished responses that reached this ending. Use an ending id of the form, and pass formId too.

    1–64 chars

  • consentenum

    Only responses with this consent. agreed for people who agreed to be called and texted, not_agreed for people the form asked who haven't agreed, not_asked for forms with no consent field. See Consent.

    One of "agreed", "not_agreed", "not_asked"

  • fromnumber

    Only responses created at or after this time, in milliseconds since the epoch.

  • tonumber

    Only responses created before this time, in milliseconds since the epoch.

  • searchstring

    Words to find in the contact details or in any answer. It looks at the name, email and phone, the answers, the labels of picked options and file names. Every word must match, and case and accents don't matter. Digits also match phone numbers written in any format. With a search, each page checks limit responses and returns the ones that match. A page can be short or even empty while nextCursor is not null, so keep paging until it is null.

    max 200 chars

  • sortenum

    How to order the responses. createdAt is the default and sorts by when they were created. status puts left responses first, then started, then finished, and asc reverses that. ending sorts by the ending's name, with unfinished responses at one end. contact sorts by the person's name, or their email or phone when there's no name. Ties go by creation time. Every sort except createdAt needs formId.

    One of "createdAt", "status", "ending", "contact"

  • orderenum

    desc is the default. With the default sort, desc lists the newest responses first.

    One of "desc", "asc"

Response

  • idstringrequired

    The export's id.

  • formIdstringrequired

    The form whose responses it exports.

  • statusenumrequired

    running while the file is being prepared, with rows counting the responses written so far. ready once you can call POST /v1/exports/{exportId}/download, and the file is kept for a day. expired once the file was deleted, so export again. failed when it went wrong, and error says why. canceled when someone stopped it.

    One of "running", "ready", "failed", "canceled", "expired"

  • rowsnumberrequired

    How many responses were written so far. Once ready, it's all of them.

  • bytesnumberrequired

    The file's size so far, in bytes.

  • filenamestringrequired

    The CSV file's name.

  • filteredbooleanrequired

    Whether any filter was on. A filtered file has "-filtered-" in its name.

  • filtersobjectrequired

    The filters and sort it was asked for, as in GET /v1/submissions.

    Show 9 fields
    • statusenum

      One of "partial", "complete"

    • stateenum

      One of "started", "left", "finished"

    • endingIdstring
    • consentenum

      One of "agreed", "not_agreed", "not_asked"

    • fromnumber
    • tonumber
    • searchstring
    • sortenum

      One of "createdAt", "status", "ending", "contact"

    • orderenum

      One of "desc", "asc"

  • errorstring or nullrequired

    Why it failed. Null otherwise.

  • minebooleanrequired

    Whether you started it. Over the API, that means with this key.

  • createdAtnumberrequired

    When it started, in milliseconds since the epoch.

  • finishedAtnumber or nullrequired

    When it stopped running, in milliseconds since the epoch. Null while it runs.

Errors answer with a status and the error shape.