List JobsBeta

Retrieve a paginated list of background jobs in your workspace, newest first.

GEThttps://api.foxreach.io/api/v1/jobs

Requires an API key with the read scope.

Query Parameters#

pageintegerquerydefault 1

Page number (starts at 1).

pageSizeintegerquerydefault 25

Number of jobs per page (1-100).

typestringquery

Filter by job type, for example lead_import or email_verification.

statusstringquery

Filter by status: pending, running, completed or failed.

Response#

dataarray

Array of job objects.

Show Job object

idstring

Job identifier.

typestring

Job type, for example lead_import or email_verification.

statusstring

pending, running, completed or failed.

progressinteger

Percent complete, 0 to 100.

totalItemsinteger

Number of items the job will process.

completedItemsinteger

Number of items processed so far.

resultobject

Result counters once the job has produced them, otherwise null. A lead import returns imported, restored, failed and, when it started a verification run, verificationJobId. A verification run returns good, risky, bad, errors and billableCount. Raw rows and failed-row details are never returned.

errorstring

Error summary when the job failed, otherwise null.

startedAtstring

ISO 8601 timestamp, or null.

completedAtstring

ISO 8601 timestamp, or null.

createdAtstring

ISO 8601 timestamp.

Errors#

Status	Description
`401`	Missing, invalid, revoked or expired API key
`403`	API key does not have the required scope: `read`

Rate Limit#

600 requests per minute, shared by every poll call in your workspace. Fixed 60-second window.
Every response includes X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset (unix epoch seconds) and X-RateLimit-Bucket (poll).
A 429 response includes a Retry-After header (seconds until the bucket resets).

For client-side patterns (Retry-After, exponential backoff, monitoring X-RateLimit-Remaining), see Rate Limiting.

Request

cURL

curl -X GET "https://api.foxreach.io/api/v1/jobs?status=running" \
  -H "X-API-Key: otr_your_key"

Python SDK (beta)

from foxreach import FoxReach

client = FoxReach(api_key="otr_your_key")
jobs = client.jobs.list(status="running")

TypeScript SDK (beta)

import { FoxReach } from "foxreach";

const client = new FoxReach({ apiKey: "otr_your_key" });
const jobs = await client.jobs.list({ status: "running" });

Response

JSON

{
  "data": [
    {
      "id": "cmjob123",
      "type": "lead_import",
      "status": "completed",
      "progress": 100,
      "totalItems": 250,
      "completedItems": 250,
      "result": { "imported": 240, "restored": 4, "failed": 6, "verificationJobId": "cmjob124" },
      "error": null,
      "startedAt": "2026-11-04T09:00:02",
      "completedAt": "2026-11-04T09:00:41",
      "createdAt": "2026-11-04T09:00:00"
    }
  ],
  "meta": {
    "page": 1,
    "pageSize": 25,
    "total": 1,
    "totalPages": 1
  }
}

Was this page helpful?

View as MarkdownLast updated November 4, 2026