Get Request

GET

api

requests

{id}

curl -X GET https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348 \
  -H "Authorization: Bearer your_api_key_here"

import requests

url = "https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348"
headers = {
    "Authorization": "Bearer your_api_key_here"
}

response = requests.get(url, headers=headers)
print(response.json())

const axios = require('axios');

const response = await axios.get(
  'https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348',
  {
    headers: {
      'Authorization': 'Bearer your_api_key_here'
    }
  }
);

console.log(response.data);

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

{
  "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
        }
      ],
      "broadcasted_at": "2024-03-15T10:30:00Z",
      "status": "completed",
      "response_by": "65f1234567890abcdef12350",
      "response_at": "2024-03-15T10:45:00Z",
      "response_data": "Approve",
      "response_time_seconds": 900.5,
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T10:45: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

string

required

Your API key for authentication

Path Parameters

string

required

The unique identifier of the request

Response

boolean

Whether an error occurred

string

Success message

object

Show data

object

The complete request object

Show request

string

Unique identifier for the request

string

ID of the loop this request belongs to

string

ID of the user who created the request

string

ID of the API key used to create the request

string

Processing urgency type (time-sensitive, deferred)

string

Content type (markdown, image)

string

Priority level (low, medium, high, critical)

string

The main content of the request

string

URL of the image to review (if applicable)

object

Additional context data

string

Platform that created the request

string

Version of the platform used

string

Type of response expected

object

Configuration for the response type

object

Default response if timeout occurs

string

ISO timestamp when the request times out

string

URL to call when request is completed

array

List of users who received the request notification

string

ISO timestamp when the request was broadcasted

string

Current status (pending, completed, timeout, cancelled)

string

ID of the user who responded (if completed)

string

ISO timestamp when the response was submitted

object

The actual response data from the reviewer

number

Time taken to respond in seconds

string

ISO timestamp when the request was created

string

ISO timestamp when the request was last updated

curl -X GET https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348 \
  -H "Authorization: Bearer your_api_key_here"

import requests

url = "https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348"
headers = {
    "Authorization": "Bearer your_api_key_here"
}

response = requests.get(url, headers=headers)
print(response.json())

const axios = require('axios');

const response = await axios.get(
  'https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348',
  {
    headers: {
      'Authorization': 'Bearer your_api_key_here'
    }
  }
);

console.log(response.data);

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

{
  "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
        }
      ],
      "broadcasted_at": "2024-03-15T10:30:00Z",
      "status": "completed",
      "response_by": "65f1234567890abcdef12350",
      "response_at": "2024-03-15T10:45:00Z",
      "response_data": "Approve",
      "response_time_seconds": 900.5,
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T10:45:00Z"
    }
  }
}

Request Status Types

Pending

Request is waiting for a reviewer response. No response yet.

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.

Cancel RequestCancel a pending request. Only requests that haven't been completed can be cancelled.

curl -X GET https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348 \
  -H "Authorization: Bearer your_api_key_here"

import requests

url = "https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348"
headers = {
    "Authorization": "Bearer your_api_key_here"
}

response = requests.get(url, headers=headers)
print(response.json())

const axios = require('axios');

const response = await axios.get(
  'https://api.hitl.sh/v1/api/requests/65f1234567890abcdef12348',
  {
    headers: {
      'Authorization': 'Bearer your_api_key_here'
    }
  }
);

console.log(response.data);

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

{
  "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
        }
      ],
      "broadcasted_at": "2024-03-15T10:30:00Z",
      "status": "completed",
      "response_by": "65f1234567890abcdef12350",
      "response_at": "2024-03-15T10:45:00Z",
      "response_data": "Approve",
      "response_time_seconds": 900.5,
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T10:45:00Z"
    }
  }
}

Getting Started

Loops

Requests

Webhooks

Authentication

Path Parameters

Response

Request Status Types

Pending

Completed

Cancelled

Timeout

Polling Strategy

Basic Polling

Exponential Backoff

Response Data Examples

Single Select Response

Multi Select Response

Rating Response

Text Response

Boolean Response

Next Steps

Add Feedback

Cancel Request

Set Up Webhooks

​Authentication

​Path Parameters

​Response

​Request Status Types

Pending

Completed

Cancelled

Timeout

​Polling Strategy

​Basic Polling

​Exponential Backoff

​Response Data Examples

​Single Select Response

​Multi Select Response

​Rating Response

​Text Response

​Boolean Response

​Next Steps

Add Feedback

Cancel Request

Set Up Webhooks

Authentication

Path Parameters

Response

Request Status Types

Polling Strategy

Basic Polling

Exponential Backoff

Response Data Examples

Single Select Response

Multi Select Response

Rating Response

Text Response

Boolean Response

Next Steps