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

{
  "error": false,
  "msg": "Loop retrieved successfully",
  "data": {
    "loop": {
      "id": "65f1234567890abcdef12345",
      "name": "Content Moderation Review",
      "description": "Review user-generated content for community guidelines compliance",
      "icon": "shield-check",
      "creator_id": "65f1234567890abcdef12346",
      "members": [
        {
          "user_id": "65f1234567890abcdef12346",
          "email": "creator@example.com",
          "status": "active",
          "joined_at": "2024-03-15T10:30:00Z"
        },
        {
          "user_id": "65f1234567890abcdef12347",
          "email": "reviewer1@example.com", 
          "status": "active",
          "joined_at": "2024-03-15T11:45:00Z"
        },
        {
          "user_id": "65f1234567890abcdef12348",
          "email": "reviewer2@example.com",
          "status": "pending",
          "joined_at": null
        }
      ],
      "member_count": 3,
      "pending_count": 1,
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T11:45:00Z"
    }
  }
}
Get comprehensive details about a specific loop by its ID. This endpoint provides complete loop information including member details, statistics, and metadata.

​
Authentication

​
Authorization
string
required
Your API key for authentication

​
Path Parameters

​
id
string
required
The unique identifier of the loop (24-character MongoDB ObjectID)

​
Response

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

{
  "error": false,
  "msg": "Loop retrieved successfully",
  "data": {
    "loop": {
      "id": "65f1234567890abcdef12345",
      "name": "Content Moderation Review",
      "description": "Review user-generated content for community guidelines compliance",
      "icon": "shield-check",
      "creator_id": "65f1234567890abcdef12346",
      "members": [
        {
          "user_id": "65f1234567890abcdef12346",
          "email": "creator@example.com",
          "status": "active",
          "joined_at": "2024-03-15T10:30:00Z"
        },
        {
          "user_id": "65f1234567890abcdef12347",
          "email": "reviewer1@example.com", 
          "status": "active",
          "joined_at": "2024-03-15T11:45:00Z"
        },
        {
          "user_id": "65f1234567890abcdef12348",
          "email": "reviewer2@example.com",
          "status": "pending",
          "joined_at": null
        }
      ],
      "member_count": 3,
      "pending_count": 1,
      "created_at": "2024-03-15T10:30:00Z",
      "updated_at": "2024-03-15T11:45:00Z"
    }
  }
}

​
Loop Information Overview

​
Member Status Types

Active Members

Users who have accepted the invitation and can receive review requests.

Pending Members

Users who have been invited but haven’t joined the loop yet.

​
Loop Statistics

This endpoint provides key metrics about your loop:
  • Total Members: Complete count of all loop participants
  • Active Members: Users ready to receive review requests
  • Pending Invitations: Outstanding invitations that need acceptance
  • Activity Timeline: Creation and last update timestamps

​
Access Control

​
Who Can View Loops

Can view complete loop details including all member information and statistics.
Can view basic loop information but with limited member details (via mobile app).
API keys can only access loops created by the same user account.

​
Use Cases

​
Monitoring Loop Health

Check if your loop has enough active members: 
def check_loop_health(loop_id, min_active_members=2):
    response = requests.get(f"https://api.hitl.sh/v1/api/loops/{loop_id}", headers=headers)
    loop_data = response.json()["data"]["loop"]
    
    active_members = loop_data["member_count"] - loop_data["pending_count"]
    
    if active_members < min_active_members:
        print(f"Warning: Loop only has {active_members} active members")
        return False
    
    return True

​
Member Management

Track pending invitations: 
function checkPendingInvitations(loopData) {
    const pendingMembers = loopData.members.filter(member => member.status === 'pending');
    
    if (pendingMembers.length > 0) {
        console.log(`${pendingMembers.length} pending invitations:`);
        pendingMembers.forEach(member => {
            console.log(`- ${member.email} (invited but not joined)`);
        });
    }
    
    return pendingMembers;
}

​
Loop Analytics

Calculate member join rate: 
from datetime import datetime

def calculate_join_rate(loop_data):
    total_members = len(loop_data["members"])
    active_members = sum(1 for m in loop_data["members"] if m["status"] == "active")
    
    if total_members == 0:
        return 0
    
    join_rate = (active_members / total_members) * 100
    return round(join_rate, 2)

# Usage
loop_data = response.json()["data"]["loop"]
join_rate = calculate_join_rate(loop_data)
print(f"Member join rate: {join_rate}%")

​
Error Handling

​
Common Error Scenarios

{
  "error": true,
  "msg": "Loop not found"
}
Causes:
  • Invalid loop ID format
  • Loop doesn’t exist
  • Loop was deleted
  • User doesn’t have access to the loop
{
  "error": true,
  "msg": "Invalid loop ID format"
}
Cause: Loop ID must be a valid 24-character MongoDB ObjectID (hexadecimal).Valid format: 65f1234567890abcdef12345
{
  "error": true,
  "msg": "Access denied to this loop"
}
Cause: API key doesn’t have permission to access this loop. Only the loop creator can access loop details via API.

​
Integration Examples

​
Loop Status Dashboard

Build a dashboard to monitor all your loops: 
def get_loop_dashboard():
    # Get all loops
    loops_response = requests.get("https://api.hitl.sh/v1/api/loops", headers=headers)
    loops = loops_response.json()["data"]["loops"]
    
    dashboard = []
    for loop in loops:
        # Get detailed info for each loop
        detail_response = requests.get(f"https://api.hitl.sh/v1/api/loops/{loop['id']}", headers=headers)
        loop_detail = detail_response.json()["data"]["loop"]
        
        dashboard.append({
            "name": loop_detail["name"],
            "id": loop_detail["id"],
            "active_members": loop_detail["member_count"] - loop_detail["pending_count"],
            "pending_members": loop_detail["pending_count"],
            "created": loop_detail["created_at"],
            "health": "healthy" if (loop_detail["member_count"] - loop_detail["pending_count"]) >= 2 else "needs_attention"
        })
    
    return dashboard

​
Automated Member Follow-up

Send reminders to pending members: 
async function followUpPendingMembers(loopId) {
    const response = await fetch(`https://api.hitl.sh/v1/api/loops/${loopId}`, {
        headers: { 'Authorization': `Bearer ${apiKey}` }
    });
    
    const loopData = await response.json();
    const loop = loopData.data.loop;
    
    const pendingMembers = loop.members.filter(member => member.status === 'pending');
    
    for (const member of pendingMembers) {
        // Send reminder email (implement your email service)
        await sendReminderEmail({
            to: member.email,
            subject: `Reminder: Join ${loop.name} loop`,
            loopName: loop.name,
            joinUrl: `https://my.hitl.sh/join/${loop.invite_code}`
        });
    }
    
    return `Sent reminders to ${pendingMembers.length} pending members`;
}

​
Next Steps

Update Loop

Modify loop details like name, description, or icon.

Manage Members

View detailed member information and manage loop membership.

Create Request

Start creating human review requests within this loop.
⌘I