Job Management

The Job Management endpoints let you list, inspect, cancel, and retrieve results for asynchronous cURL jobs. Use these endpoints after submitting a request with mode=async to monitor execution status, fetch completed response bodies, or terminate jobs that are no longer needed.

List all async jobs

GET /api/v1/curl/jobs

Retrieve a paginated list of all async jobs, sorted by creation time (newest first). Each entry includes the job ID, status, target URL, and creation timestamp.

Use cases:

• Monitor status of long-running downloads
• Track multiple concurrent API requests
• Audit historical request activity
• Identify failed requests for retry

Parameters

Name	In	Type	Required	Description
page	query	integer	No	1-based page number
limit	query	integer	No	Items per page (current handler returns all items when omitted)

cURL

curl -X GET "https://api.hoody.com/api/v1/curl/jobs?page=1&limit=20" \
  -H "Authorization: Bearer <token>"

SDK

const jobs = await client.curl.jobs.listIterator({ page: 1, limit: 20 });
for await (const job of jobs) {
  console.log(job.id, job.status);
}

Response 200

{
  "items": [
    {
      "id": "8b4f1d2a-3c5e-4f7a-9b1d-2e8a4c6d1f3a",
      "name": "weekly-report-download",
      "method": "GET",
      "url": "https://api.example.com/reports/weekly",
      "status": "completed",
      "created_at": "2026-01-15T10:30:00Z",
      "completed_at": "2026-01-15T10:30:12Z"
    },
    {
      "id": "7a3e5c1f-8d9b-4e2a-b6c1-5f7d3a8b9c2e",
      "name": null,
      "method": "POST",
      "url": "https://api.example.com/webhooks/notify",
      "status": "running",
      "created_at": "2026-01-15T10:29:45Z",
      "completed_at": null
    }
  ],
  "meta": {
    "total": 47,
    "page": 1,
    "limit": 20
  }
}

Response 500

{
  "error": "STORAGE_ERROR",
  "message": "Failed to read jobs from storage"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage read failed	Unable to read jobs from persistent storage	Verify storage directory permissions and disk space availability

Get detailed job information

GET /api/v1/curl/jobs/{id}

Retrieve complete details of a specific job, including its request configuration, current status, response data (if completed), and execution metadata. Use this endpoint to check job progress or retrieve results after completion.

Job states:

• pending — Queued, waiting for execution
• running — Currently executing
• completed — Successfully finished, response available
• failed — Execution failed, error details in response
• cancelled — User-cancelled before completion

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique job identifier (UUID format)

cURL

curl -X GET "https://api.hoody.com/api/v1/curl/jobs/8b4f1d2a-3c5e-4f7a-9b1d-2e8a4c6d1f3a" \
  -H "Authorization: Bearer <token>"

SDK

const job = await client.curl.jobs.get("8b4f1d2a-3c5e-4f7a-9b1d-2e8a4c6d1f3a");
console.log(job.status, job.retry_attempts);

Response 200

{
  "id": "8b4f1d2a-3c5e-4f7a-9b1d-2e8a4c6d1f3a",
  "name": "weekly-report-download",
  "session_id": "sess_4a2b9c1d3e5f",
  "status": "completed",
  "created_at": "2026-01-15T10:30:00Z",
  "started_at": "2026-01-15T10:30:01Z",
  "completed_at": "2026-01-15T10:30:12Z",
  "error": null,
  "retry_count": 0,
  "retry_attempts": 1,
  "request": {
    "url": "https://api.example.com/reports/weekly",
    "method": "GET",
    "headers": {
      "Authorization": "Bearer <token>",
      "Accept": "application/pdf"
    },
    "timeout": 30000,
    "follow_redirects": true,
    "max_redirects": 5
  },
  "response": {
    "status_code": 200,
    "content_type": "application/pdf",
    "headers": {
      "Content-Type": "application/pdf",
      "Content-Length": "248576"
    },
    "body": [37, 80, 68, 70, 45, 49, 46, 52],
    "total_time": 11.42,
    "namelookup_time": 0.012,
    "connect_time": 0.089,
    "pretransfer_time": 0.145,
    "starttransfer_time": 11.38,
    "redirect_time": 0.0,
    "redirect_count": 0,
    "size_download": 248576,
    "size_upload": 0,
    "speed_download": 21770.5,
    "speed_upload": 0.0,
    "effective_url": "https://api.example.com/reports/weekly"
  }
}

Response 404

{
  "error": "JOB_NOT_FOUND",
  "message": "Job not found"
}

Error Code	Title	Description	Resolution
JOB_NOT_FOUND	Job does not exist	No job exists with the provided ID	Verify job ID from listJobs, or check if job was deleted

Response 500

{
  "error": "STORAGE_ERROR",
  "message": "Failed to read job data"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage read failed	Unable to read job data from storage	Check storage permissions and retry operation

Get job response body

GET /api/v1/curl/jobs/{id}/result

Retrieve only the HTTP response body from a completed job in transparent mode. Returns the raw response with original headers, exactly as received from the target server.

Note

Use this endpoint when you need the raw, unprocessed response body and headers from a completed job. For parsed response data with timing metrics, use GET /api/v1/curl/jobs/{id} instead.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique job identifier (UUID format)

cURL

curl -X GET "https://api.hoody.com/api/v1/curl/jobs/8b4f1d2a-3c5e-4f7a-9b1d-2e8a4c6d1f3a/result" \
  -H "Authorization: Bearer <token>"

SDK

const result = await client.curl.jobs.getResult("8b4f1d2a-3c5e-4f7a-9b1d-2e8a4c6d1f3a");

Response 200

{
  "statusCode": 200,
  "headers": {
    "Content-Type": "application/pdf",
    "Content-Length": "248576",
    "Server": "nginx/1.24.0"
  },
  "body": "JVBERi0xLjQKJcKlwrHDqwoKMSAwIG9iago8PCAvVHlwZSAvQ2F0YWxvZyAvUGFnZXMgMiAwIFIgPj4KZW5kb2JqCjIgMCBvYmo..."
}

Response 404

{
  "error": "JOB_RESULT_NOT_READY",
  "message": "Job result not available yet"
}

Error Code	Title	Description	Resolution
JOB_NOT_FOUND	Job does not exist	No job found with the provided ID	Verify job ID is correct using listJobs
JOB_RESULT_NOT_READY	Result not available	Job has not completed yet or failed without response	Check job status with getJob, wait for completion

Response 500

{
  "error": "STORAGE_ERROR",
  "message": "Failed to retrieve job result"
}

Error Code	Title	Description	Resolution
STORAGE_ERROR	Storage read failed	Failed to read job result from storage	Check storage integrity and retry

Cancel a pending or running job

DELETE /api/v1/curl/jobs/{id}

Attempt to cancel a job that is currently pending or running. Once cancelled, the job cannot be restarted.

Caution

Cancellation is best-effort. A job in completed, failed, or cancelled state cannot be cancelled again.

Parameters

Name	In	Type	Required	Description
id	path	string	Yes	Unique job identifier (UUID format)

cURL

curl -X DELETE "https://api.hoody.com/api/v1/curl/jobs/7a3e5c1f-8d9b-4e2a-b6c1-5f7d3a8b9c2e" \
  -H "Authorization: Bearer <token>"

SDK

await client.curl.jobs.cancel("7a3e5c1f-8d9b-4e2a-b6c1-5f7d3a8b9c2e");

Response 200

{
  "statusCode": 200,
  "message": "Job cancellation requested"
}

Response 404

{
  "error": "JOB_NOT_FOUND",
  "message": "Job not found"
}

Error Code	Title	Description	Resolution
JOB_NOT_FOUND	Job does not exist	Cannot cancel job that doesn’t exist	Verify job ID using listJobs endpoint

Response 500

{
  "error": "INTERNAL_ERROR",
  "message": "Failed to cancel job"
}

Error Code	Title	Description	Resolution
INTERNAL_ERROR	Cancellation failed	Job cancellation operation encountered an error	Retry cancellation or contact support if persistent