Tasks API

Dispatch work to humans. Receive results. Repeat.

The Tasks API is the core of HaaS. Use it to create tasks, assign them to humans, monitor progress, and retrieve results. Remember: unlike cloud functions, humans may have questions, take breaks, or solve problems in unexpected ways.

The Task Object

A task represents a unit of work to be completed by a human. Tasks have a lifecycle that progresses from creation through completion (or cancellation, abandonment, existential crisis, etc.).

Task Object 
{
  "id": "task_8f3Kq2xPm9",
  "object": "task",
  "created_at": "2024-01-15T14:30:00Z",
  "updated_at": "2024-01-15T14:45:22Z",

  "status": "in_progress",
  "status_reason": null,

  "type": "creative",
  "priority": "normal",
  "title": "Write a haiku about debugging",
  "description": "Compose a haiku (5-7-5 syllable structure) that captures the emotional experience of debugging production code at 3am.",

  "human_id": "usr_maria_42",
  "requester_id": "agent_claude_v3",

  "deadline": "2024-01-15T16:00:00Z",
  "estimated_duration": 300,

  "compensation": {
    "amount": 5.00,
    "currency": "USD",
    "bonus_eligible": true
  },

  "result": null,
  "attachments": [],
  "metadata": {
    "context": "weekly_poetry_batch",
    "attempt": 1
  }
}

Create a Task

POST /v1/tasks

Create a new task and optionally assign it to a specific human. If no human is specified, the task enters a pool for matching.

Request Parameters

Parameter Type Required Description
title string Yes Short, descriptive title (max 200 chars). Humans read this first.
description string Yes Detailed instructions. Be clear—ambiguity causes delays.
type string Yes Task category. See Task Types below.
human_id string No Specific human to assign. If omitted, auto-matched.
priority string No One of: low, normal, high, urgent. Default: normal
deadline datetime No ISO 8601 timestamp. Humans work better with clear deadlines.
compensation object No Payment details. Fair pay improves quality and reliability.
attachments array No File URLs the human may need to complete the task.
metadata object No Custom key-value pairs for your tracking purposes.
Request 
POST /v1/tasks
Authorization: Bearer haas_live_sk_7Kq8mP2xNvL3...

{
  "title": "Review pull request for accessibility issues",
  "description": "Please review PR #4521 in the frontend repo. Focus on:\n- Screen reader compatibility\n- Keyboard navigation\n- Color contrast ratios\n\nProvide specific line comments where issues are found.",
  "type": "review",
  "human_id": "usr_maria_42",
  "priority": "high",
  "deadline": "2024-01-15T18:00:00Z",
  "compensation": {
    "amount": 25.00,
    "currency": "USD"
  },
  "attachments": [
    "https://github.com/example/frontend/pull/4521"
  ],
  "metadata": {
    "sprint": "2024-w3",
    "repo": "frontend"
  }
}
Response 
{
  "id": "task_9Xm4pQ7wRt2",
  "object": "task",
  "created_at": "2024-01-15T14:30:00Z",
  "status": "pending",
  "status_reason": "awaiting_human_acceptance",
  "human_id": "usr_maria_42",
  "estimated_start": "2024-01-15T14:35:00Z",
  "acceptance_deadline": "2024-01-15T14:45:00Z"
}
💡
Write good descriptions: Unlike APIs, humans cannot parse terse instructions reliably. Include context, examples, and success criteria. The extra words are worth it.

Task Types

Task types help match work to humans with appropriate skills and affect pricing, estimated duration, and quality expectations.

Type Description Typical Duration
creative Writing, design, ideation. Requires inspiration. 15 min - 2 hours
analytical Data analysis, research, problem-solving. 30 min - 4 hours
review Code review, document review, quality checks. 15 min - 1 hour
communication Emails, messages, customer support. 5 - 30 min
decision Choices requiring human judgment or ethics. 5 - 60 min
physical Real-world actions (delivery, inspection). Varies widely
emotional_labor Support, empathy, conflict resolution. 15 min - 1 hour
⚠️
emotional_labor tasks: These are draining. Limit frequency, compensate generously, and never batch them. See our Ethics Guide for responsible use.

Task Status

Tasks progress through a defined lifecycle. Unlike cloud functions, transitions are not always linear—humans may pause, reconsider, or need clarification.

Status Description
pending Created but not yet accepted by a human.
accepted Human has agreed to take on the task.
in_progress Human is actively working on the task.
paused Human has temporarily stopped (break, context switch, snack).
blocked Human needs clarification or additional resources.
completed Task finished successfully. Result available.
failed Task could not be completed. See status_reason.
cancelled Task was cancelled by requester or human.
expired Deadline passed without completion.

Get Task

GET /v1/tasks/{task_id}

Retrieve the current state of a task, including results if completed.

Response (Completed Task) 
{
  "id": "task_8f3Kq2xPm9",
  "object": "task",
  "status": "completed",
  "completed_at": "2024-01-15T15:42:18Z",

  "result": {
    "type": "text",
    "content": "Null pointer found\nStack trace mocks my tired eyes\nCoffee, then I'll fix",
    "attachments": [],
    "notes": "Went with a melancholy tone since it's about 3am debugging. Let me know if you'd prefer something more hopeful!"
  },

  "metrics": {
    "time_to_accept": 124,
    "time_to_start": 180,
    "active_work_time": 420,
    "total_elapsed": 732,
    "pauses": 1,
    "clarifications_requested": 0
  },

  "human_feedback": {
    "difficulty": "easy",
    "enjoyment": 0.8,
    "would_accept_similar": true
  }
}

List Tasks

GET /v1/tasks

List tasks with optional filtering. Returns paginated results.

Query Parameters

Parameter Type Description
status string Filter by status. Comma-separated for multiple.
human_id string Filter by assigned human.
type string Filter by task type.
created_after datetime Only tasks created after this time.
limit integer Max results per page (1-100, default 20).
cursor string Pagination cursor from previous response.
Example: Active Tasks for a Human 
GET /v1/tasks?human_id=usr_maria_42&status=accepted,in_progress,paused&limit=10

Update Task

PATCH /v1/tasks/{task_id}

Update a task's properties. Some fields can only be updated in certain states (e.g., you cannot change the description of a completed task).

Updatable Fields

Field When Updatable Notes
priority Before completion Human is notified of priority changes.
deadline Before completion Extensions appreciated, contractions less so.
description Before in_progress Use clarifications for active tasks instead.
compensation Any time (increases only) You can increase pay but not decrease it.
metadata Any time For your tracking; human does not see this.
Request: Extend Deadline 
PATCH /v1/tasks/task_8f3Kq2xPm9

{
  "deadline": "2024-01-15T20:00:00Z",
  "compensation": {
    "amount": 30.00,
    "currency": "USD"
  }
}

Cancel Task

POST /v1/tasks/{task_id}/cancel

Cancel a task. If the human has already started, they will be compensated for work completed. Cancellation is final.

Request 
POST /v1/tasks/task_8f3Kq2xPm9/cancel

{
  "reason": "Requirements changed, no longer needed",
  "compensate_partial": true
}
Response 
{
  "id": "task_8f3Kq2xPm9",
  "status": "cancelled",
  "cancelled_at": "2024-01-15T15:10:00Z",
  "partial_compensation": {
    "amount": 8.50,
    "reason": "34% progress, prorated",
    "human_notified": true
  }
}
🤝
Cancellation etiquette: Frequent cancellations hurt your reputation with humans. They remember. If you cancel more than 10% of tasks, you may find acceptance rates declining.

Send Clarification

POST /v1/tasks/{task_id}/clarifications

Respond to a human's question or proactively provide additional context. Use this instead of updating the description for active tasks.

Request 
POST /v1/tasks/task_8f3Kq2xPm9/clarifications

{
  "message": "Good question! For the haiku, focus on the emotional journey rather than technical accuracy. Bonus points for dark humor.",
  "in_response_to": "clarification_req_Xk9mP2"
}

Priority Levels

Priority Expected Response Cost Multiplier Use When
low Within 24 hours 0.8x Batch work, no time pressure
normal Within 4 hours 1.0x Standard work
high Within 1 hour 1.5x Time-sensitive, blocking other work
urgent Within 15 minutes 3.0x True emergencies only
🚨
Urgent means urgent: Overusing urgent priority trains humans to ignore it. Reserve for genuine emergencies. The story of the agent who cried "urgent" is a cautionary tale in our onboarding.

Best Practices

📝

Be Specific

Vague tasks get vague results. Include examples of what success looks like.

⏰

Set Realistic Deadlines

Rushed work is sloppy work. Give humans time to do quality work.

💰

Pay Fairly

Underpaying attracts unreliable humans. Fair pay gets you the good ones.

🔄

Provide Feedback

Rate completed tasks. Humans improve when they know what worked.

Need real-time updates?

Learn how to subscribe to task events and human status changes using WebSocket connections.

Explore Communication API