Skip to main content
GET
/
api
/
v1
/
convert
/
status
/
:jobId
Poll status
curl --request GET \
  --url https://api.example.com/api/v1/convert/status/:jobId
Poll the status of a conversion job that was started with "async": true or that timed out during synchronous processing.

​
Request

​
Headers

HeaderValueRequired
AuthorizationBearer YOUR_API_TOKENYes

​
Path parameters

ParameterTypeRequiredDescription
jobIdstringYesThe job ID returned from the convert endpoint

​
Example request

curl https://api.formswrite.com/api/v1/convert/status/456 \
  -H "Authorization: Bearer YOUR_API_TOKEN"

​
Response

The response includes the current job state, progress information, and the result when the job completes.
FieldTypeDescription
successbooleanWhether the API call succeeded
jobIdstringThe job ID
statestringCurrent job state: waiting, active, completed, or failed
progressnumberProgress percentage (0–100)
currentStepstringDescription of the current processing step
resultobjectConversion result (only present when state is completed)
errorstringError message (only present when state is failed)

​
Job states

StateDescription
waitingJob is queued and waiting to be processed
activeJob is currently being processed
completedJob finished successfully — check the result field
failedJob failed — check the error field

​
Response examples

​
Processing

{
  "success": true,
  "jobId": "456",
  "state": "active",
  "progress": 45,
  "currentStep": "Extracting questions"
}

​
Completed

{
  "success": true,
  "jobId": "456",
  "state": "completed",
  "progress": 100,
  "currentStep": "",
  "result": {
    "success": true,
    "documentId": "1BxiMVs0XRA5nFMdKvBdBZjgmUUqptlbs74OgVE2upms",
    "documentName": "Biology Exam",
    "isQuiz": true,
    "mergedContent": {
      "title": "Biology Exam",
      "questions": [...]
    }
  }
}
The result from the status endpoint contains the raw analysis output. To get the final converted file, use the synchronous mode of the convert endpoint instead, or build your own conversion step using the returned mergedContent.

​
Failed

{
  "success": true,
  "jobId": "456",
  "state": "failed",
  "progress": 0,
  "currentStep": "",
  "error": "Document could not be accessed. Please check sharing permissions."
}

​
Not found

{
  "success": false,
  "message": "Job not found"
}

​
Polling strategy

We recommend polling every 3–5 seconds. Most documents are analyzed within 30–60 seconds. 
async function waitForConversion(jobId, apiToken) {
  const maxAttempts = 60;

  for (let i = 0; i < maxAttempts; i++) {
    const response = await fetch(
      `https://api.formswrite.com/api/v1/convert/status/${jobId}`,
      { headers: { Authorization: `Bearer ${apiToken}` } }
    );
    const data = await response.json();

    if (data.state === 'completed') {
      return data.result;
    }
    if (data.state === 'failed') {
      throw new Error(data.error);
    }

    // Wait 3 seconds before next poll
    await new Promise(resolve => setTimeout(resolve, 3000));
  }

  throw new Error('Polling timed out');
}