Skip to content
Survey Coder Pro Survey Coder Pro

Get async job status

GET
/v2/jobs/{id}
 
curl --request GET \
  --url https://api.surveycoder.io/v2/jobs/job_1a2b3c4d5e6f7a8b9c0d1e2f \
  --header 'x-api-key: <x-api-key>'

Poll an async job by ID. Returns progress percentage while processing, the full result on completion, or an error object on failure. Jobs auto-expire after 24 hours.

Authorizations

Section titled “Authorizations ”

Parameters

Section titled “ Parameters ”

Path Parameters

Section titled “Path Parameters ”
id
required
string
/^job_[a-f0-9]{24}$/
Example 
job_1a2b3c4d5e6f7a8b9c0d1e2f

Job ID returned by an async endpoint (e.g. job_a1b2c3...).

Responses

Section titled “ Responses ”

200

Section titled “200 ”

Job found

Media type application/json
object
success
required
boolean
data
required

Full job object with optional result or error.

object
id
required

Unique job identifier.

string
type
required

Kind of background work.

string
Allowed values: codebook_generation auto_coding one_call
status
required

Current job status.

string
Allowed values: queued processing completed failed
progress
required

Progress counters for the job.

object
processed
required

Number of items processed so far.

integer
total
required

Total number of items to process.

integer
percentage
required

Completion percentage (0-100).

integer
<= 100
created_at
required

ISO 8601 timestamp when the job was created.

string format: date-time
updated_at
required

ISO 8601 timestamp of the last status update.

string format: date-time
result

Present only when status is completed. Shape depends on the job type. For one_call jobs, matches the data field of CodeResponseSync.

object
key
additional properties
any
error

Error details when a job fails.

object
code
required

Machine-readable error code.

string
message
required

Human-readable error message.

string
Example 
{
  "success": true,
  "data": {
    "id": "job_1a2b3c4d5e6f7a8b9c0d1e2f",
    "type": "codebook_generation",
    "status": "queued",
    "progress": {
      "processed": 120,
      "total": 500,
      "percentage": 24
    },
    "error": {
      "code": "CODING_FAILED",
      "message": "Codebook generation failed after 3 retries"
    }
  }
}

401

Section titled “401 ”

Missing or invalid API key.

Media type application/json

Standard error envelope.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code. See the error reference for the full list.

string
message
required

Human-readable explanation of what went wrong.

string
request_id

Echo of the X-Request-Id header, when provided.

string format: uuid
doc_url

Link to documentation for this specific error code.

string format: uri
Example 
{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "x-api-key header is required",
    "doc_url": "https://docs.surveycoder.io/errors/unauthorized"
  }
}

404

Section titled “404 ”

Resource not found.

Media type application/json

Standard error envelope.

object
success
required
boolean
error
required
object
code
required

Machine-readable error code. See the error reference for the full list.

string
message
required

Human-readable explanation of what went wrong.

string
request_id

Echo of the X-Request-Id header, when provided.

string format: uuid
doc_url

Link to documentation for this specific error code.

string format: uri
Example 
{
  "success": false,
  "error": {
    "code": "NOT_FOUND",
    "message": "Project not found",
    "doc_url": "https://docs.surveycoder.io/errors/not-found"
  }
}