Job Management

List, inspect, cancel, and retrieve results of async curl jobs. These endpoints operate on background HTTP requests previously submitted with mode=async. Jobs progress through the following states: pending → running → completed, failed, or cancelled.

Use these endpoints when you need to monitor long-running operations, audit historical request activity, or retry failed jobs.

List jobs

`GET /api/v1/curl/jobs`

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

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 (returns all items when omitted)

Response

{
  "items": [
    {
      "id": "7f3a4d8e-2b1c-4f9a-8e6d-1a2b3c4d5e6f",
      "name": "nightly-export",
      "status": "completed",
      "method": "POST",
      "url": "https://api.example.com/v1/exports",
      "created_at": "2025-01-15T08:42:11.000Z",
      "completed_at": "2025-01-15T08:42:14.000Z"
    },
    {
      "id": "9b8c7d6e-5f4a-3b2c-1d0e-9f8a7b6c5d4e",
      "name": "webhook-retry",
      "status": "running",
      "method": "GET",
      "url": "https://hooks.example.com/deliveries/12345",
      "created_at": "2025-01-15T08:41:58.000Z",
      "completed_at": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 47
  }
}

{
  "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

SDK Usage

const iterator = await client.curl.jobs.listIterator({ page: 1, limit: 20 });

curl -X GET "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.icu/api/v1/curl/jobs?page=1&limit=20"

Get job details

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

Retrieve complete details of a single job, including its request configuration, current status, response data (if completed), and execution metadata.

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)

Response

{
  "id": "7f3a4d8e-2b1c-4f9a-8e6d-1a2b3c4d5e6f",
  "name": "nightly-export",
  "status": "completed",
  "session_id": "sess_a1b2c3d4e5f6",
  "created_at": "2025-01-15T08:42:11.000Z",
  "started_at": "2025-01-15T08:42:11.500Z",
  "completed_at": "2025-01-15T08:42:14.000Z",
  "error": null,
  "retry_count": 2,
  "retry_attempts": 1,
  "request": {
    "url": "https://api.example.com/v1/exports",
    "method": "POST",
    "headers": {
      "Content-Type": "application/json",
      "Authorization": "Bearer &lt;token&gt;"
    },
    "data": "{\"format\":\"csv\"}",
    "mode": "async",
    "response": "json",
    "timeout": 30000,
    "follow_redirects": true
  },
  "response": {
    "status_code": 200,
    "headers": {
      "Content-Type": "application/json",
      "X-Request-Id": "req_abc123"
    },
    "body": [123, 34, 115, 116, 97, 116, 117, 115, 34, 58, 32, 34, 111, 107, 34, 125],
    "total_time": 2.487,
    "namelookup_time": 0.012,
    "connect_time": 0.045,
    "pretransfer_time": 0.046,
    "starttransfer_time": 0.892,
    "redirect_time": 0.0,
    "redirect_count": 0,
    "size_download": 17,
    "size_upload": 15,
    "speed_download": 6.83,
    "speed_upload": 6.03,
    "effective_url": "https://api.example.com/v1/exports"
  }
}

{
  "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

{
  "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

SDK Usage

const job = await client.curl.jobs.get("7f3a4d8e-2b1c-4f9a-8e6d-1a2b3c4d5e6f");

curl -X GET "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.icu/api/v1/curl/jobs/7f3a4d8e-2b1c-4f9a-8e6d-1a2b3c4d5e6f"

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.

Parameters

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

Response

HTTP/1.1 200 OK
Content-Type: application/json
X-Request-Id: req_abc123

{"status": "ok", "export_id": "exp_9876"}

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

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

{
  "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

SDK Usage

const result = await client.curl.jobs.getResult("7f3a4d8e-2b1c-4f9a-8e6d-1a2b3c4d5e6f");

curl -X GET "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.icu/api/v1/curl/jobs/7f3a4d8e-2b1c-4f9a-8e6d-1a2b3c4d5e6f/result"

Cancel a 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.

Parameters

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

Response

{
  "id": "9b8c7d6e-5f4a-3b2c-1d0e-9f8a7b6c5d4e",
  "status": "cancelled"
}

{
  "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

{
  "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

SDK Usage

await client.curl.jobs.cancel("9b8c7d6e-5f4a-3b2c-1d0e-9f8a7b6c5d4e");

curl -X DELETE "https://{projectId}-{containerId}-curl-1.{server}.containers.hoody.icu/api/v1/curl/jobs/9b8c7d6e-5f4a-3b2c-1d0e-9f8a7b6c5d4e"