GET
/
v1
/
requests
/
{id}
curl -X GET https://api.hitl.sh/v1/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/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/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/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.