Skip to content

Beautiful Open-Source Form Builder

4.0 KB
Raw Blame
---
openapi: get /open/forms/{id}/submissions/export/status/{job_id}
---

# Check Export Status

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

## Authentication & Scope

Requires `forms-read` ability.

## Request

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

### Path Parameters

| Parameter | Type   | Description             |
| --------- | ------ | ----------------------- |
| id        | number | Numeric ID of the form. |
| job_id    | string | Export job identifier.  |

## Response

### Processing Status

```json
{
    "status": "processing",
    "progress": 65,
    "processed_submissions": 650,
    "total_submissions": 1000,
    "file_url": null,
    "error_message": null,
    "expires_at": null,
    "created_at": "2024-06-12T09:15:23.000Z",
    "updated_at": "2024-06-12T09:16:10.000Z",
    "job_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}
```

### Completed Status

```json
{
    "status": "completed",
    "progress": 100,
    "processed_submissions": 1000,
    "total_submissions": 1000,
    "file_url": "https://storage.example.com/exports/form-123-submissions-2024-06-12-09-15-23.csv",
    "error_message": null,
    "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": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}
```

### Failed Status

```json
{
    "status": "failed",
    "progress": 0,
    "processed_submissions": null,
    "total_submissions": null,
    "file_url": null,
    "error_message": "Database connection timeout",
    "expires_at": null,
    "created_at": "2024-06-12T09:15:23.000Z",
    "updated_at": "2024-06-12T09:15:45.000Z",
    "job_id": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d"
}
```

## Response Fields

| Field                   | Type   | Description                                          |
| ----------------------- | ------ | ---------------------------------------------------- |
| `status`                | string | Job status: `queued`, `processing`, `completed`, or `failed` |
| `progress`              | number | Completion percentage (0-100)                        |
| `job_id`                | string | Export job identifier                                |
| `processed_submissions` | number | Number of submissions processed so far               |
| `total_submissions`     | number | Total number of submissions to process               |
| `file_url`              | string | Download URL for completed exports                   |
| `expires_at`            | string | File expiration timestamp (workspace policy, 24 hours by default) |
| `error_message`         | string | Error description for failed exports                 |
| `created_at`            | string | Job creation timestamp                               |
| `updated_at`            | string | Last update timestamp                                |

<Note>
    Every field is always present. Fields that do not apply to the current job
    state are `null`.
</Note>

<Warning>
    The download URL is a bearer link. It remains valid until `expires_at`,
    according to the workspace file-link policy (24 hours by default).
</Warning>

## Error Responses

`404 Not Found` – Export job not found, has expired, or belongs to another form.

`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:

<Steps>
<Step title="Start export">
    Call the export endpoint and receive a `job_id`.
</Step>

<Step title="Poll status">
    Use the `job_id` to check export progress every few seconds.
    <Tip>
        Avoid polling too frequently. Check every 2-5 seconds for optimal
        performance.
    </Tip>
</Step>

<Step title="Download file">
    When status is `completed`, use the `file_url` to download your CSV file.
    
    <Warning>
    Download the file before the `expires_at` timestamp. The workspace policy is 24 hours by default.
    </Warning>
</Step>
</Steps>