Job Management

Use these endpoints to list, inspect, retrieve results from, and cancel asynchronous cURL jobs. A job is created whenever a request is submitted with mode=async. Jobs progress through the states pending, running, completed, failed, or cancelled, and are persisted in storage so you can audit historical activity or poll long-running downloads.

List Jobs

GET /api/v1/curl/jobs

Retrieve a paginated list of all async jobs, ordered by creation time (newest first). Each entry is a compact summary; use the Get Job endpoint for the full record.

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

Response

200

{
  "items": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "status": "completed",
      "url": "https://api.example.com/users/42",
      "method": "GET",
      "name": "Fetch user profile",
      "created_at": "2024-01-15T10:30:00Z",
      "completed_at": "2024-01-15T10:30:02Z"
    },
    {
      "id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
      "status": "running",
      "url": "https://files.example.com/large-dataset.zip",
      "method": "GET",
      "name": null,
      "created_at": "2024-01-15T10:29:45Z",
      "completed_at": null
    }
  ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 2
  }
}

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

SDK Usage

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-curl-1.node-us.containers.hoody.com', token: process.env.HOODY_TOKEN });

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

cURL

curl -X GET 'https://{projectId}-{containerId}-curl-1.node-us.containers.hoody.com/api/v1/curl/jobs?page=1&limit=20' \
  -H "Authorization: Bearer <token>"

Get Job Details

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

Retrieve the full record of a single job, including the original request configuration, current status, response payload (when 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 error
• cancelled — User-cancelled before completion

Parameters

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

Response

200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "completed",
  "name": "Fetch user profile",
  "session_id": null,
  "request": {
    "url": "https://api.example.com/users/42",
    "method": "GET",
    "headers": {
      "Accept": "application/json"
    },
    "mode": "async",
    "response": "json",
    "timeout": 30000
  },
  "response": {
    "status_code": 200,
    "headers": {
      "Content-Type": "application/json"
    },
    "body": [123, 34, 105, 100, 34, 58, 52, 50, 125],
    "total_time": 0.234,
    "namelookup_time": 0.012,
    "connect_time": 0.045,
    "pretransfer_time": 0.046,
    "starttransfer_time": 0.123,
    "redirect_time": 0,
    "redirect_count": 0,
    "size_download": 13,
    "size_upload": 0,
    "speed_download": 55.5,
    "speed_upload": 0,
    "effective_url": "https://api.example.com/users/42"
  },
  "retry_count": 0,
  "retry_attempts": 0,
  "created_at": "2024-01-15T10:30:00Z",
  "started_at": "2024-01-15T10:30:00.500Z",
  "completed_at": "2024-01-15T10:30:02Z",
  "error": null
}

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

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

SDK Usage

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-curl-1.node-us.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.curl.jobs.get('550e8400-e29b-41d4-a716-446655440000');

cURL

curl -X GET 'https://{projectId}-{containerId}-curl-1.node-us.containers.hoody.com/api/v1/curl/jobs/550e8400-e29b-41d4-a716-446655440000' \
  -H "Authorization: Bearer <token>"

Get Job Result

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

Retrieve only the raw HTTP response body from a completed job, returned in transparent mode (original headers plus raw bytes). The endpoint returns the exact response received from the target server.

Caution

This endpoint only returns a result when the job status is completed and the response was originally captured in transparent mode. A 404 is returned for jobs that are still pending/running or that finished without a usable response.

Parameters

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

Response

200

{
  "status_code": 200,
  "headers": {
    "Content-Type": "text/html; charset=utf-8",
    "Server": "nginx/1.24.0"
  },
  "body": [60, 104, 49, 62, 72, 101, 108, 108, 111, 44, 32, 119, 111, 114, 108, 100, 33, 60, 47, 104, 49, 62]
}

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

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

SDK Usage

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-curl-1.node-us.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.curl.jobs.getResult('550e8400-e29b-41d4-a716-446655440000');

cURL

curl -X GET 'https://{projectId}-{containerId}-curl-1.node-us.containers.hoody.com/api/v1/curl/jobs/550e8400-e29b-41d4-a716-446655440000/result' \
  -H "Authorization: Bearer <token>"

Cancel 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; submit a new request to retry the work.

Parameters

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

Response

200

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "status": "cancelled",
  "message": "Job cancellation requested"
}

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 the listJobs endpoint

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

SDK Usage

TypeScript SDK

import { HoodyClient } from 'hoody-sdk';

const client = new HoodyClient({ baseURL: 'https://{projectId}-{containerId}-curl-1.node-us.containers.hoody.com', token: process.env.HOODY_TOKEN });

await client.curl.jobs.cancel('550e8400-e29b-41d4-a716-446655440000');

cURL

curl -X DELETE 'https://{projectId}-{containerId}-curl-1.node-us.containers.hoody.com/api/v1/curl/jobs/550e8400-e29b-41d4-a716-446655440000' \
  -H "Authorization: Bearer <token>"