Jobs API

Jobs represent asynchronous background tasks in Synapse, primarily used for long-running operations like contact exports. When you trigger an export, Synapse creates a job, processes it in the background, and stores the result file for download.

Endpoints

Method	Path	Description
`GET`	`/v1/jobs`	List jobs with optional filters
`GET`	`/v1/jobs/{job_id}`	Get job status and progress
`GET`	`/v1/jobs/{job_id}/download`	Download the result file

All endpoints require JWT authentication and the contacts:read permission.

Authentication

bash

curl "https://synapse-api.pyrx.tech/v1/jobs" \

-H "Authorization: Bearer eyJhbGciOiJS..."

Missing permission returns:

json

{

"detail": "Missing permission: contacts:read"

}

List Jobs

bash

curl "https://synapse-api.pyrx.tech/v1/jobs?type=contact_export&status=completed&page=1&per_page=20" \

-H "Authorization: Bearer eyJhbGciOiJS..."

Query Parameters

Parameter	Type	Default	Description
`type`	string		Filter by job type (e.g. `contact_export`)
`status`	string		Filter by status (e.g. `pending`, `processing`, `completed`, `failed`)
`page`	integer	`1`	Page number (starts at 1)
`per_page`	integer	`20`	Items per page (1--100)

Response

json

{

"data": [

{

"id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",

"type": "contact_export",

"status": "completed",

"total_rows": 5432,

"processed_rows": 5432,

"success_count": 5432,

"error_count": 0,

"errors": [],

"result_file_name": "contacts_2026-04-18.csv",

"result_file_size": 1048576,

"params": {

"format": "csv",

"segment_id": null

"created_by": "m1e2m3b4-e5r6-7890-abcd-ef1234567890",

"started_at": "2026-04-18T10:00:01Z",

"completed_at": "2026-04-18T10:00:12Z",

"expires_at": "2026-04-25T10:00:12Z",

"created_at": "2026-04-18T10:00:00Z",

"updated_at": "2026-04-18T10:00:12Z",

"progress_percent": 100

}

"total": 1,

"page": 1,

"per_page": 20

}

Get Job Status

bash

curl "https://synapse-api.pyrx.tech/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \

-H "Authorization: Bearer eyJhbGciOiJS..."

Returns a single JobResponse object with the same shape as the list items above.

Job Types

Type	Description
`contact_export`	Export contacts to CSV or JSON

Job Statuses

Status	Meaning
`pending`	Job is created but has not started processing yet
`processing`	Job is actively running
`completed`	Job finished successfully -- result file is available for download
`failed`	Job encountered an error and could not complete

Progress Tracking

The response includes real-time progress fields:

Field	Description
`total_rows`	Total number of rows to process (set once processing begins)
`processed_rows`	Number of rows processed so far
`success_count`	Rows successfully processed
`error_count`	Rows that failed
`progress_percent`	Computed percentage: `processed_rows / total_rows * 100`
`errors`	Array of error details for individual row failures

Download Result File

bash

curl "https://synapse-api.pyrx.tech/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download" \

-H "Authorization: Bearer eyJhbGciOiJS..." \

-o contacts_export.csv

Returns the result file as a streaming download with appropriate Content-Type and Content-Disposition headers.

Prerequisites

The job must have status: "completed". Attempting to download a pending, processing, or failed job returns 400.
The result file must still exist. Files have an expiration date (expires_at). After expiration, the file is deleted and the download returns 404.

Response Headers

Header	Example
`Content-Type`	`text/csv` or `application/json`
`Content-Disposition`	`attachment; filename="contacts_2026-04-18.csv"`
`Content-Length`	`1048576`

Polling Pattern

Jobs are asynchronous. The typical workflow for an export:

Trigger an export (e.g. via the Contacts API) -- this creates a job and returns the job_id.
Poll for status -- call GET /v1/jobs/{job_id} periodically until status is completed or failed.
Download the result -- once completed, call GET /v1/jobs/{job_id}/download to retrieve the file.

bash

# Step 1: Trigger a contact export (returns job_id)

curl -X POST "https://synapse-api.pyrx.tech/v1/contacts/export" \

-H "Authorization: Bearer eyJhbGciOiJS..." \

-H "Content-Type: application/json" \

-d '{ "format": "csv" }'

# Step 2: Poll for completion

curl "https://synapse-api.pyrx.tech/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890" \

-H "Authorization: Bearer eyJhbGciOiJS..."

# Repeat until status is "completed" or "failed"

# Step 3: Download

curl "https://synapse-api.pyrx.tech/v1/jobs/a1b2c3d4-e5f6-7890-abcd-ef1234567890/download" \

-H "Authorization: Bearer eyJhbGciOiJS..." \

-o contacts.csv

Tip

A reasonable polling interval is 2--5 seconds for small exports (under 10,000 rows) and 5--10 seconds for larger exports. Use the progress_percent field to show a progress bar in your UI.

Error Codes

Status	Description
`400`	Job is not completed (cannot download)
`403`	Missing `contacts:read` permission
`404`	Job not found, or result file has expired