Skip to main content
GET
/
v1
/
api
/
requests
/
{id}
curl -X GET https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348 \
  -H "Authorization: Bearer your_api_key_here"

{
  "error": false,
  "msg": "Request retrieved successfully",
  "data": {
    "request": {
      "id": "65f1234567890abcdef12348",
      "loop_id": "65f1234567890abcdef12345",
      "creator_id": "65f1234567890abcdef12346",
      "api_key_id": "65f1234567890abcdef12349",
      "processing_type": "time-sensitive",
      "type": "markdown",
      "priority": "high",
      "request_text": "Please review this user-generated content for community guidelines compliance.",
      "image_url": null,
      "context": {
        "user_id": "user123",
        "post_id": "post456",
        "automated_flags": ["potential_spam"]
      },
      "platform": "api",
      "platform_version": "1.0.0",
      "response_type": "single_select",
      "response_config": {
        "options": ["Approve", "Reject", "Needs Changes"]
      },
      "default_response": "Approve",
      "timeout_at": "2024-03-15T11:30:00Z",
      "callback_url": "https://example.com/webhook/response",
      "broadcasted_to": [
        {
          "user_id": "65f1234567890abcdef12350",
          "email": "reviewer1@example.com",
          "role": "member",
          "notification_sent": true,
          "notification_error": null
        },
        {
          "user_id": "65f1234567890abcdef12351",
          "email": "reviewer2@example.com", 
          "role": "member",
          "notification_sent": true,
          "notification_error": null
        }
      ],
      "broadcasted_at": "2024-03-15T10:30:00Z",
      "status": "pending",
      "response_by": null,
      "response_at": null,
      "response_data": null,
      "response_time_seconds": null,
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T10:30:00Z"
    }
  }
}
Get comprehensive information about a specific request. This endpoint is useful for polling request status and retrieving the human reviewer’s response once completed.

​
Authentication

​
Authorization
string
required
Your API key for authentication

​
Path Parameters

​
id
string
required
The unique identifier of the request

​
Response

​
error
boolean
Whether an error occurred
​
msg
string
Success message
​
data
object
curl -X GET https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348 \
  -H "Authorization: Bearer your_api_key_here"

{
  "error": false,
  "msg": "Request retrieved successfully",
  "data": {
    "request": {
      "id": "65f1234567890abcdef12348",
      "loop_id": "65f1234567890abcdef12345",
      "creator_id": "65f1234567890abcdef12346",
      "api_key_id": "65f1234567890abcdef12349",
      "processing_type": "time-sensitive",
      "type": "markdown",
      "priority": "high",
      "request_text": "Please review this user-generated content for community guidelines compliance.",
      "image_url": null,
      "context": {
        "user_id": "user123",
        "post_id": "post456",
        "automated_flags": ["potential_spam"]
      },
      "platform": "api",
      "platform_version": "1.0.0",
      "response_type": "single_select",
      "response_config": {
        "options": ["Approve", "Reject", "Needs Changes"]
      },
      "default_response": "Approve",
      "timeout_at": "2024-03-15T11:30:00Z",
      "callback_url": "https://example.com/webhook/response",
      "broadcasted_to": [
        {
          "user_id": "65f1234567890abcdef12350",
          "email": "reviewer1@example.com",
          "role": "member",
          "notification_sent": true,
          "notification_error": null
        },
        {
          "user_id": "65f1234567890abcdef12351",
          "email": "reviewer2@example.com", 
          "role": "member",
          "notification_sent": true,
          "notification_error": null
        }
      ],
      "broadcasted_at": "2024-03-15T10:30:00Z",
      "status": "pending",
      "response_by": null,
      "response_at": null,
      "response_data": null,
      "response_time_seconds": null,
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T10:30:00Z"
    }
  }
}

​
Request Status Types

Pending

Request is waiting for a reviewer to claim it. No response yet.

Claimed

A reviewer has claimed the request and is working on it.

Completed

Reviewer has submitted their response. Check response_data field.

Cancelled

Request was cancelled before completion.

Timeout

Request timed out. default_response was used as the final response.

​
Polling Strategy

​
Basic Polling

Poll every 30 seconds for time-sensitive requests: 
import time
import requests

def poll_request_status(request_id, api_key, max_attempts=120):
    """Poll request status for up to 1 hour (120 * 30 seconds)"""
    url = f"https://api.hitl.sh/v1/api/requests/{request_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    for attempt in range(max_attempts):
        response = requests.get(url, headers=headers)
        data = response.json()
        
        if data["data"]["request"]["status"] in ["completed", "cancelled", "timeout"]:
            return data["data"]["request"]
        
        time.sleep(30)  # Wait 30 seconds before next poll
    
    return None  # Timeout reached

​
Exponential Backoff

More efficient polling with increasing intervals: 
import time
import requests

def poll_with_backoff(request_id, api_key):
    """Poll with exponential backoff"""
    url = f"https://api.hitl.sh/v1/api/requests/{request_id}"
    headers = {"Authorization": f"Bearer {api_key}"}
    
    intervals = [5, 10, 30, 60, 120, 300]  # seconds
    
    for interval in intervals:
        response = requests.get(url, headers=headers)
        data = response.json()
        
        status = data["data"]["request"]["status"]
        if status in ["completed", "cancelled", "timeout"]:
            return data["data"]["request"]
        
        time.sleep(interval)
    
    return None

​
Response Data Examples

​
Single Select Response

{
  "response_data": "Approve"
}

​
Multi Select Response

{
  "response_data": ["Policy Violation", "Spam"]
}

​
Rating Response

{
  "response_data": 4
}

​
Text Response

{
  "response_data": "The content looks good but could benefit from better formatting."
}

​
Boolean Response

{
  "response_data": true
}

​
Next Steps

Add Feedback

Provide feedback on completed requests to improve reviewer performance.

Cancel Request

Cancel a pending request if it’s no longer needed.

Set Up Webhooks

Get real-time notifications instead of polling for status updates.
⌘I