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": [...]
    }
  }
}
Async mode currently runs analysis only, not the format conversion. The result from the status endpoint contains the extracted questions (mergedContent) but not the final converted file or URL. To get the file, call the convert endpoint again without async: true — that single call analyzes and converts in one step.For now, prefer synchronous mode unless you specifically need the analyzed-questions payload separately from the conversion step.

​
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');
}