# Job Management

**Page:** api/curl/jobs

[Download Raw Markdown](./api/curl/jobs.md)

---

{/* AUTO-GENERATED — Do not edit manually. Regenerate with: npm run docs:api:generate */}



## 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) |



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


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


```json
{
  "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
  }
}
```


```json
{
  "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) |



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


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


```json
{
  "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"
  }
}
```


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


```json
{
  "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.


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) |



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


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


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


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


```json
{
  "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.


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) |



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


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


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


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


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