Skip to main content

​
Overview

A Job is a batch of tracks that HumanStandard processes asynchronously. You submit a list of URLs (or file IDs), and we return results via webhook as each track completes — no polling required. Jobs are ideal for:
  • Scanning a backlog or existing catalog
  • Nightly ingestion pipelines
  • Supply chain review queues

​
Creating a job

POST https://app.jobsbyhumans.com/api/v1/jobs
Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

{
  "name": "Q1 Catalog Scan",
  "items": [
    { "item_id": "track-001", "url": "https://cdn.example.com/01.mp3" },
    { "item_id": "track-002", "url": "https://cdn.example.com/02.mp3" },
    { "item_id": "track-003", "url": "https://cdn.example.com/03.mp3" }
  ],
  "webhook_url": "https://yourapi.com/webhooks/humanstandard"
}

import requests, os

job = requests.post(
    "https://app.jobsbyhumans.com/api/v1/jobs",
    headers={"Authorization": f"Bearer {os.environ['HS_API_KEY']}"},
    json={
        "name": "Q1 Catalog Scan",
        "items": [
            {"item_id": "track-001", "url": "https://cdn.example.com/01.mp3"},
            {"item_id": "track-002", "url": "https://cdn.example.com/02.mp3"},
        ],
        "webhook_url": "https://yourapi.com/webhooks/hs",
    }
).json()

print(job["id"])  # job_abc123
print(job["status"])  # "queued"

​
Job status

Poll or use webhooks to track progress: 
GET https://app.jobsbyhumans.com/api/v1/jobs/{job_id}

{
  "id": "job_abc123",
  "name": "Q1 Catalog Scan",
  "status": "processing",
  "total": 100,
  "processed": 47,
  "succeeded": 45,
  "failed": 2,
  "verdict_counts": {
    "human": 38,
    "suspicious": 7
  },
  "created_at": "2026-02-27T10:00:00Z",
  "completed_at": null
}

​
Fetching results

Once the job is complete, retrieve all results: 
GET https://app.jobsbyhumans.com/api/v1/jobs/{job_id}/results
Results are returned as newline-delimited JSON (NDJSON), one record per track. See Reading Results for the full record schema.

​
Webhook delivery

If you provide a webhook_url, we call it when the job completes: 
{
  "event": "job.complete",
  "job_id": "job_abc123",
  "summary": {
    "total": 100,
    "succeeded": 98,
    "failed": 2,
    "verdict_counts": { "human": 81, "suspicious": 17 }
  }
}
Individual track results are available via the results endpoint above, or you can configure per-track webhooks to receive a call for each track as it finishes. See Webhooks.

​
Large catalogs

For catalogs over 10,000 tracks, use a manifest URL instead of an inline items array: 
{
  "name": "Full Catalog",
  "manifest_url": "https://your-storage.com/manifest.ndjson",
  "webhook_url": "https://yourapi.com/webhooks/hs"
}
The manifest is a newline-delimited JSON file, one item per line: 
{"item_id": "track-001", "url": "https://cdn.example.com/01.mp3"}
{"item_id": "track-002", "url": "https://cdn.example.com/02.mp3"}