Get Loop by ID

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

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

Show data

loop

object

Complete loop information

Show loop

string

Unique identifier for the loop

name

string

Name of the loop

description

string

Description of the loop

icon

string

Icon identifier

creator_id

string

ID of the loop creator

members

array

Array of loop members with status

Show member

user_id

string

ID of the member user

string

Email address of the member

status

string

Member status (pending, active)

joined_at

string

ISO timestamp when member joined (null for pending)

member_count

integer

Total number of members in the loop

pending_count

integer

Number of pending member invitations

created_at

string

ISO timestamp of loop creation

updated_at

string

ISO timestamp of last update

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

Loop Creators

Can view complete loop details including all member information and statistics.

Loop Members

Can view basic loop information but with limited member details (via mobile app).

API Key Access

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

Loop Not Found

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

Invalid Loop ID Format

{
  "error": true,
  "msg": "Invalid loop ID format"
}

Cause: Loop ID must be a valid 24-character MongoDB ObjectID (hexadecimal).Valid format: 65f1234567890abcdef12345

Access Denied

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

Getting Started

Loops

Requests

Webhooks

Authentication

Path Parameters

Response

Loop Information Overview

Member Status Types

Active Members

Pending Members

Loop Statistics

Access Control

Who Can View Loops

Use Cases

Monitoring Loop Health

Member Management

Loop Analytics

Error Handling

Common Error Scenarios

Integration Examples

Loop Status Dashboard

Automated Member Follow-up

Next Steps

Update Loop

Manage Members

Create Request

Getting Started

Loops

Requests

Webhooks

Documentation Index

​Authentication

​Path Parameters

​Response

​Loop Information Overview

​Member Status Types

Active Members

Pending Members

​Loop Statistics

​Access Control

​Who Can View Loops

​Use Cases

​Monitoring Loop Health

​Member Management

​Loop Analytics

​Error Handling

​Common Error Scenarios

​Integration Examples

​Loop Status Dashboard

​Automated Member Follow-up

​Next Steps

Update Loop

Manage Members

Create Request

Authentication

Path Parameters

Response

Loop Information Overview

Member Status Types

Loop Statistics

Access Control

Who Can View Loops

Use Cases

Monitoring Loop Health

Member Management

Loop Analytics

Error Handling

Common Error Scenarios

Integration Examples

Loop Status Dashboard

Automated Member Follow-up

Next Steps