Skip to main content
GET
/
open
/
forms
/
{id}
/
submissions
/
export
/
{job_id}
/
status
Check Export Status
curl --request GET \
  --url https://api.opnform.com/open/forms/{id}/submissions/export/{job_id}/status \
  --header 'Authorization: Bearer <token>'
{
  "progress": 50,
  "form_id": 123,
  "user_id": 123,
  "job_id": "<string>",
  "processed_submissions": 123,
  "total_submissions": 123,
  "file_url": "<string>",
  "expires_at": "2023-11-07T05:31:56Z",
  "error_message": "<string>",
  "created_at": "2023-11-07T05:31:56Z",
  "updated_at": "2023-11-07T05:31:56Z"
}

​
Check Export Status

Check the status and progress of an asynchronous CSV export job.

​
Authentication & Scope

Requires forms-read ability.

​
Request

GET /open/forms/{id}/submissions/export/{job_id}/status HTTP/1.1
Host: api.opnform.com
Authorization: Bearer <token>

​
Path Parameters

ParameterTypeDescription
idnumberNumeric ID of the form.
job_idstringExport job identifier.

​
Response

​
Processing Status

{
    "status": "processing",
    "progress": 65,
    "form_id": 123,
    "user_id": 456,
    "processed_submissions": 650,
    "total_submissions": 1000,
    "created_at": "2024-06-12T09:15:23.000Z",
    "updated_at": "2024-06-12T09:16:10.000Z",
    "job_id": "export_abc123def456"
}

​
Completed Status

{
    "status": "completed",
    "progress": 100,
    "form_id": 123,
    "user_id": 456,
    "processed_submissions": 1000,
    "total_submissions": 1000,
    "file_url": "https://storage.example.com/exports/form-123-submissions-2024-06-12-09-15-23.csv",
    "expires_at": "2024-06-13T09:15:23.000Z",
    "created_at": "2024-06-12T09:15:23.000Z",
    "updated_at": "2024-06-12T09:16:30.000Z",
    "job_id": "export_abc123def456"
}

​
Failed Status

{
    "status": "failed",
    "progress": 0,
    "form_id": 123,
    "user_id": 456,
    "error_message": "Database connection timeout",
    "created_at": "2024-06-12T09:15:23.000Z",
    "updated_at": "2024-06-12T09:15:45.000Z",
    "job_id": "export_abc123def456"
}

​
Response Fields

FieldTypeDescription
statusstringJob status: processing, completed, or failed
progressnumberCompletion percentage (0-100)
form_idnumberID of the form being exported
user_idnumberID of the user who initiated the export
job_idstringExport job identifier
processed_submissionsnumberNumber of submissions processed so far
total_submissionsnumberTotal number of submissions to process
file_urlstringDownload URL for completed exports
expires_atstringFile expiration timestamp (24 hours from completion)
error_messagestringError description for failed exports
created_atstringJob creation timestamp
updated_atstringLast update timestamp
Only status, progress, form_id, user_id, job_id, created_at, and updated_at are always present. Other fields appear based on the job state.
Export files are automatically deleted after 24 hours for security and storage management.

​
Error Responses

404 Not Found – Export job not found or has expired. 403 Forbidden – The token lacks forms-read or you don’t have access.

​
Usage Example

After initiating an export that returns is_async: true, poll this endpoint to track progress:
1

Start export

Call the export endpoint and receive a job_id.
2

Poll status

Use the job_id to check export progress every few seconds.
Avoid polling too frequently. Check every 2-5 seconds for optimal performance.
3

Download file

When status is completed, use the file_url to download your CSV file.
Download the file promptly as it expires in 24 hours.

Authorizations

​
Authorization
string
header
required

Personal Access Token

Path Parameters

​
id
number
required
​
job_id
string
required

Export job identifier

Response

Export job status

​
status
enum<string>

Current status of the export job

Available options:
processing,
completed,
failed
​
progress
number

Completion percentage (0-100)

Required range: 0 <= x <= 100
​
form_id
number

ID of the form being exported

​
user_id
number

ID of the user who initiated the export

​
job_id
string

Export job identifier

​
processed_submissions
number | null

Number of submissions processed so far

​
total_submissions
number | null

Total number of submissions to process

​
file_url
string<uri> | null

Download URL for completed exports

​
expires_at
string<date-time> | null

File expiration timestamp (24 hours from completion)

​
error_message
string | null

Error description for failed exports

​
created_at
string<date-time>

Job creation timestamp

​
updated_at
string<date-time>

Last update timestamp