Build with Hive.

Use your Hive API key in the Authorization: Bearer $HIVE_API_KEY header. Send JSON request bodies with Content-Type: application/json. Keep your key on your server.

Examples use https://hive-osint-dev.172-86-73-30.sslip.io as the base URL. Check GET /capabilities before requesting a service. Use a unique Idempotency-Key for tunnel creation and Books submissions; reuse it only when repeating the same request.

Set HIVE_API_KEY in your environment, then run this request. The response includes a cdp_url for connecting your automation tool.

curl --fail-with-body -X POST "https://hive-osint-dev.172-86-73-30.sslip.io/browser/session" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Browsers use direct access from Hive by default. To enable a managed proxy, send {"use_proxy":true,"country":"AR"}. Country, region, ASN, mobile network, and identity constraints apply to proxy connections. A country value alone does not change a direct session’s exit IP.

Next, follow the browser automation guide to open a page with Playwright.

Create a resource with POST /resources/phone, /resources/mail, /resources/captcha, or /resources/network. Keep the returned resource_id. Read the recorded state with GET, poll for progress with POST, and DELETE the resource when finished.

Phone requests use service and a two-letter country. Mail can specify a domain. Captcha requests use captcha_type with site_key and page_url, or image_b64 for an image. For a browser-bound challenge, supply browser_context with the submitting browser’s user_agent and relevant cookies. Cookie entries use name, value, domain, path, and optional http_only, secure, and expires. Hive forwards that context for the solve without storing cookie values in resource records. A token is ready to submit when the resource becomes ready; the target website still decides whether to accept it. The reference below lists each field.

Exchanges return one result: send messages to POST /exchange/llm or a prompt to POST /exchange/image.

{
  "messages": [
    {
      "role": "user",
      "content": "Summarize this paragraph."
    }
  ],
  "max_tokens": 200
}

Search for people, find company employees, and retrieve public profiles, posts, comments, and reactions. Use filters and pagination to select the results you need.

Check /capabilities for service availability and the API reference for each operation’s request fields. Pagination is finite: limit is 1–1000, page is 1–100, and pages is 1–20, with tighter limits on individual target and filter lists.

• POST /scrapers/linkedin/people/search
• POST /scrapers/linkedin/company/employees
• POST /scrapers/linkedin/profile/details
• POST /scrapers/linkedin/profile/posts
• POST /scrapers/linkedin/post/search
• POST /scrapers/linkedin/post/comments
• POST /scrapers/linkedin/profile/comments
• POST /scrapers/linkedin/profile/reactions

{
  "profiles": [
    "https://www.linkedin.com/in/<profile-id>/"
  ],
  "detail_level": "full"
}

Find candidate people and retrieve public profiles and posts on Instagram, X, Facebook, and TikTok; discover username candidates with Sherlock, search Google, and find image matches or text with Google Lens. Use the same Hive bearer key and strict snake_case JSON bodies for every operation. Unknown fields and invalid targets are rejected before work begins.

Profile requests accept 1–10 handles or canonical public URLs in profiles. Facebook also accepts numeric IDs and profile.php URLs. Results contain items, count, and unresolved. Each entry echoes the exact target and zero-based input_index, in input order, including duplicates. Unresolved reasons are not_found, private, unavailable, malformed_data, or ambiguous; omitted profiles are unavailable, not proof of nonexistence. Resolved entries include public source links, and available identity, biography, image, verification, and count fields. Missing optional fields are omitted; profiles can be private, sparse, renamed, or unavailable.

Sherlock accepts 1–5 usernames of up to 64 characters and a limit of 1–100 per distinct username (default 20). Every result has username, site, profile_url, and status: candidate. Matching handles do not establish identity. truncated: true means a work or result limit omitted results; null means completeness is unknown.

Google accepts 1–5 queries, each up to 512 characters and 32 words; pages is 1–3 per query (default 1), and limit is 1–100 results per distinct query (default 20). Optional country and language select a supported two-letter country and search interface language. Organic results preserve query, rank, title, url, and an optional snippet.

Google Lens accepts one public HTTPS image_url or a private uploaded asset_id without credentials or private addresses, plus distinct search_types: visual, exact, and/or text. The URL is at most 4096 characters. limit is 1–100 total records (default 20), interleaved in requested type order. Visual and exact matches carry a title and public URL with optional image metadata; text records carry extracted text. A valid search may return no matches. Results do not promise completeness, totals, or a next page.

Google and Sherlock return up to 500 items for five inputs, grouped in input order; duplicate inputs are collected once. Sherlock scans each username independently so earlier inputs cannot consume later inputs’ collection windows. X account creation dates use ISO 8601 UTC; an ambiguous verification flag without badge type or blue status becomes null.

operation_health provides each operation’s reason, observed_at (Unix time), and retry_after_s. Reasons distinguish rate limiting, timeout, invalid response, limited capacity, service unavailability, missing resources and invalid requests. Capacity is shared across operations and bearer keys on the deployment. Retry timing is a minimum recheck delay; a null value means no delay is known. Elapsed time does not establish recovery. Accounting recovery can clear a capacity failure to unverified until a new search succeeds. Job recovery still uses the original key.

Read scrapers.<name>.status and operation_status from GET /capabilities. unconfigured means no active configuration; configured means all operations are unverified; usable means at least one observed success with no recorded failure; degraded means an operation has a known failure. A usable LinkedIn service does not establish that all eight operations work. Observations survive restart and reset when service configuration changes. Discovery never launches research.

Calls have finite execution limits and create no lease. Do not automatically repeat a timed-out or disconnected research call: work may already have completed. Social posts and people search support same-key recovery, as do Lens jobs. The older synchronous LinkedIn, profile/details, Sherlock, Google and Lens search routes do not support idempotent replay. Errors use bad_request, unauthorized, not_found, idempotency_conflict, expired, rate_limited, unavailable, or upstream_timeout. Invalid Hive authentication returns 401. Invalid fields return 400 with safe field detail before execution. Service failures return 503 unavailable; retained job errors and capability operation status use the same code. Keep using your Hive key. Respect retry_after_s when present.

Upload private image bytes with POST /scrapers/assets and Content-Type image/jpeg, image/png, or image/webp (10 MiB maximum). Use the returned asset_id instead of image_url. Images are encrypted, bearer-scoped, and retained for 24 hours. Their bytes are sent to the image-search service for the requested search. Download with GET /scrapers/assets/{asset_id}; delete with DELETE /scrapers/assets/{asset_id}.

Submit Lens work through POST /scrapers/google_lens/jobs with a required Idempotency-Key. The 202 response contains a poll_url for GET /scrapers/google_lens/jobs/{job_id}. Repeat the same key and body after a lost submission to retrieve the same job. Poll until completed (with result), failed, or outcome_unknown. An interrupted run is never automatically restarted. Results expire after 24 hours (410); keys stay reserved for seven days. Different bodies under one key return 409.

Lens unwraps supported Google redirect links. Embedded thumbnails have a bearer-authenticated Hive image_url, image_sha256, and image_kind: thumbnail. These hashes identify the returned thumbnail bytes, not full-resolution originals. Resolve relative image paths against your Hive origin; send your Hive key only to Hive, never to public image hosts.

Instagram, X, Facebook and TikTok expose native people/search: a free-text query (1–200 characters), up to five locations hints (1–100 characters), and limit 1–50. Hints are appended in caller order to one query; ambiguous names remain text, and city and employer filters are not enforced. The response reports effective_query, location_handling and filters_enforced: false. Instagram commas become spaces to keep one search. Candidates reuse profile fields and add the exact query, absolute rank, status: candidate and missing_fields. Missing biography/avatar fields remain null; collection-wide partial status is carried on every page. Facebook returns people with canonical profile URLs and nullable usernames or IDs; its location line is not a biography. Opaque people links retain their source URL without an inferred handle or numeric ID; details/posts require supported handle or numeric targets. Facebook cards without a usable source profile URL are omitted and make the whole collection partial; if every returned card is unusable, the search fails. TikTok returns user cards. Candidates are not verified identities and have no lookup target attribution.

People search uses the same job, key and cached-page workflow as posts, with at most 50 candidates in native order after identity deduplication. Keep the same query, locations and limit on later pages. No extra profile enrichment occurs. Replays and cached pages never repeat a search. A valid empty result differs from a failed search; completeness remains unknown. Check discovery health separately from profile lookup and posts in operation_status.

Instagram, X, Facebook and TikTok also expose profile/posts. Initial requests require Idempotency-Key; send Prefer: respond-async for a prompt 202 job, or wait up to 20 seconds for a page. Poll GET /scrapers/jobs/{job_id} with your bearer. Repeat the original key and body to recover the same job; results expire after 24 hours.

Posts accept 1–10 profiles and a total page limit of 1–50. Later pages send the same body plus result_id and page, without requiring a key or starting another collection. The cached window contains up to 50 posts per unique target (40 for Facebook) and 500 attributed items. Target outcomes preserve input order and duplicates; a resolved zero-post account differs from an unresolved target. Source authors, carousel order, video thumbnails, actual tags and separate caption mentions are preserved. Facebook covers public people and pages, including numeric profiles, and reports history_scope: recent_public_timeline: usually 25–40 recent public posts. Cached pages cannot retrieve older history. An empty Facebook response remains unresolved when a zero-post count cannot be established. TikTok preserves ordered slideshow photos, playable references when supplied, and separate cover thumbnails; the post page URL is not video bytes. Author country does not establish a post geotag. Null metadata and history_complete: null indicate unknown information. Public media references can expire; send Hive credentials only to Hive.

Set retain_media: true to preserve returned photos and video thumbnails as private JPEG/PNG/WebP evidence. Each media item reports retention_status, a fixed retention_reason, and an optional asset with its authenticated relative URL, exact-byte SHA-256, size, MIME and expiry. The original source URL and original/thumbnail role remain separate. Bounds are 20 unique images, 10 MiB and 40 million pixels each, 32 MiB downloaded per job, two concurrent downloads and up to 30 seconds within the remaining job deadline. Assets share the bearer/global image quotas and expire after 24 hours. Videos remain public references. Unresolved targets, media failures and retention limits set collection-wide partial status on every cached page, even if the affected item is on another page. Duplicate sources reuse assets; replay never redownloads, including after deletion or expiry. Keep the same retention value on cached page requests.

Recover a submission and read its cached pages

Use an Idempotency-Key of 1–200 printable ASCII characters without spaces. It binds your bearer, service, operation, ordered business request and limit. A different body under the same key, or a changed body/limit with result_id, returns 409 idempotency_conflict. Foreign or wrong-operation references return 404 not_found; expired results return 410 expired. Replay tombstones reserve keys for seven days. Reads never renew expiry. A terminal failed or outcome_unknown job cannot relaunch through replay; keep the key after an interruption.

A 202 submission includes Location, Retry-After: 2 and, when requested, Preference-Applied: respond-async. Polling returns HTTP 200 with the job envelope; completion puts the first page under result. Completed replays and cached pages return HTTP 200 even with Prefer: respond-async. Initial collection starts at page 1; later pages are 1–500 and must stay inside the collected window. An out-of-window page returns 400 bad_request. Follow next_page until null. Polls, replays and cached pages perform zero additional work.

The Bash workflow below needs curl, jq and sha256sum. Choose one service/operation and preserve its key and request. It demonstrates an explicit same-key replay, bounded polling, a second cached page when available, and an authenticated image download. A thumbnail hash identifies that thumbnail’s exact bytes; an original image hash identifies the retained original bytes.

# Run in Bash with curl, jq and sha256sum installed.
set -euo pipefail
: "${HIVE_API_KEY:?Set your Hive bearer in the environment}"
HIVE_ORIGIN="https://hive-osint-dev.172-86-73-30.sslip.io"
HIVE_SERVICE="instagram"  # instagram, x, facebook or tiktok
HIVE_OPERATION="profile/posts"
# Keep this key and the exact request after a disconnect; use a new key only
# for an intentional new collection. Do not enable shell tracing.
HIVE_RESEARCH_KEY="investigation-social-001"
request='{"profiles":["nasa"],"limit":2,"retain_media":true}'
# For native people discovery instead, set these before calling submit:
# HIVE_OPERATION="people/search"
# request='{"query":"José García","locations":["Madrid"],"limit":2}'
submit() {
  curl --fail-with-body --max-time 30 -sS \
    "$HIVE_ORIGIN/scrapers/$HIVE_SERVICE/$HIVE_OPERATION" \
    -H "Authorization: Bearer $HIVE_API_KEY" \
    -H "Content-Type: application/json" \
    -H "Idempotency-Key: $HIVE_RESEARCH_KEY" \
    -H "Prefer: respond-async" --data "$request"
}
reply="$(submit)"
# If the response was lost, run submit again with the SAME key and request.
# This explicit replay also demonstrates recovery without another collection.
reply="$(submit)"
for ((poll=0; poll<180; poll++)); do
  status="$(jq -r '.status // "completed"' <<< "$reply")"
  case "$status" in
    completed) break ;;
    failed|outcome_unknown)
      jq '{job_id,status,error}' <<< "$reply"
      exit 1 ;;  # Keep the key; a new key would start separate work.
    pending|running) ;;
    *) exit 1 ;;
  esac
  poll_url="$(jq -r '.poll_url' <<< "$reply")"
  [[ "$poll_url" =~ ^/scrapers/jobs/[a-zA-Z0-9_-]+$ ]]
  sleep 2
  reply="$(curl --fail-with-body --max-time 30 -sS \
    "$HIVE_ORIGIN$poll_url" -H "Authorization: Bearer $HIVE_API_KEY")"
done
[[ "$(jq -r '.status // "completed"' <<< "$reply")" == completed ]] || exit 1
page="$(jq '.result // .' <<< "$reply")"
jq '{result_id,page,count,collected_count,next_page,partial}' <<< "$page"
# The first completed page is stable. Follow next_page only when present.
if [[ "$(jq -r '.next_page' <<< "$page")" != null ]]; then
  next_request="$(jq --argjson page "$page" \
    '. + {result_id:$page.result_id,page:$page.next_page}' <<< "$request")"
  curl --fail-with-body --max-time 30 -sS \
    "$HIVE_ORIGIN/scrapers/$HIVE_SERVICE/$HIVE_OPERATION" \
    -H "Authorization: Bearer $HIVE_API_KEY" \
    -H "Content-Type: application/json" --data "$next_request"
fi
# Hash one retained original image or thumbnail from the first page.
asset="$(jq -c '[.items[].media[]? | select(.retention_status == "retained")][0] // null' <<< "$page")"
if [[ "$asset" != null ]]; then
  asset_url="$(jq -r '.asset.url' <<< "$asset")"
  [[ "$asset_url" =~ ^/scrapers/assets/[a-zA-Z0-9_-]+$ ]]
  curl --fail-with-body --max-time 30 -sS \
    "$HIVE_ORIGIN$asset_url" -H "Authorization: Bearer $HIVE_API_KEY" \
    --output retained-image.bin
  expected="$(jq -r '.asset.sha256' <<< "$asset")"
  printf '%s  retained-image.bin\n' "$expected" | sha256sum --check -
  jq '{role,sha256:.asset.sha256,expires_at:.asset.expires_at}' <<< "$asset"
fi

Examples for each operation

These response shapes are illustrative. Social submission examples show the initial 202 job separately from the completed page under the polled result. A completed replay can return the page directly with 200. Public data and optional fields can differ.

{
  "profiles": [
    "nasa"
  ]
}

{
  "items": [
    {
      "username": "nasa",
      "profile_url": "https://www.instagram.com/nasa/",
      "display_name": "NASA",
      "target": "nasa",
      "input_index": 0
    }
  ],
  "count": 1,
  "unresolved": []
}

{
  "Idempotency-Key": "instagram-profile-posts-001",
  "Prefer": "respond-async"
}

curl --fail-with-body --max-time 30 -sS "https://hive-osint-dev.172-86-73-30.sslip.io/scrapers/instagram/profile/posts" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: instagram-profile-posts-001" \
  -H "Prefer: respond-async" \
  --data '{"profiles":["nasa"],"limit":2}'

{
  "profiles": [
    "nasa"
  ],
  "limit": 2
}

{
  "job_id": "rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service": "instagram",
  "operation": "profile/posts",
  "status": "pending",
  "created_at": 1789913600,
  "expires_at": 1790000000,
  "poll_url": "/scrapers/jobs/rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "result": null,
  "error": null
}

{
  "items": [
    {
      "target": "nasa",
      "input_index": 0,
      "post_id": "123",
      "url": "https://www.instagram.com/p/example/",
      "author": {
        "username": "nasa",
        "profile_url": "https://www.instagram.com/nasa"
      },
      "timestamp": "2026-09-01T12:00:00+00:00",
      "text": "Public post example.",
      "media": [],
      "geotag": null,
      "tagged_users": null,
      "mentions": null,
      "context": []
    }
  ],
  "count": 1,
  "result_id": "rresult_11111111111111111111111111111111",
  "page": 1,
  "limit": 2,
  "next_page": null,
  "collected_count": 1,
  "collection_limit": 500,
  "expires_at": 1790000000,
  "truncated": null,
  "partial": false,
  "targets": [
    {
      "target": "nasa",
      "input_index": 0,
      "status": "resolved",
      "collected_count": 1,
      "reason": null
    }
  ],
  "unresolved": [],
  "per_target_limit": 50,
  "history_complete": null
}

{
  "Idempotency-Key": "instagram-people-search-001",
  "Prefer": "respond-async"
}

curl --fail-with-body --max-time 30 -sS "https://hive-osint-dev.172-86-73-30.sslip.io/scrapers/instagram/people/search" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: instagram-people-search-001" \
  -H "Prefer: respond-async" \
  --data '{"query":"José García","locations":["Madrid"],"limit":2}'

{
  "query": "José García",
  "locations": [
    "Madrid"
  ],
  "limit": 2
}

{
  "job_id": "rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service": "instagram",
  "operation": "people/search",
  "status": "pending",
  "created_at": 1789905600,
  "expires_at": 1789992000,
  "poll_url": "/scrapers/jobs/rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "result": null,
  "error": null
}

{
  "items": [
    {
      "query": "José García",
      "rank": 1,
      "status": "candidate",
      "username": "example_person",
      "profile_url": "https://www.instagram.com/example_person",
      "profile_id": "123456",
      "display_name": "José García",
      "biography": null,
      "image_url": "https://images.example.com/avatar.jpg",
      "missing_fields": [
        "biography"
      ]
    }
  ],
  "count": 1,
  "result_id": "rresult_22222222222222222222222222222222",
  "page": 1,
  "limit": 2,
  "next_page": null,
  "collected_count": 1,
  "collection_limit": 50,
  "expires_at": 1789992000,
  "truncated": null,
  "partial": true,
  "query": "José García",
  "locations": [
    "Madrid"
  ],
  "effective_query": "José García Madrid",
  "location_handling": "query_hint",
  "filters_enforced": false
}

{
  "profiles": [
    "nasa"
  ]
}

{
  "items": [
    {
      "username": "nasa",
      "profile_url": "https://x.com/NASA",
      "display_name": "NASA",
      "target": "nasa",
      "input_index": 0
    }
  ],
  "count": 1,
  "unresolved": []
}

{
  "Idempotency-Key": "x-profile-posts-001",
  "Prefer": "respond-async"
}

curl --fail-with-body --max-time 30 -sS "https://hive-osint-dev.172-86-73-30.sslip.io/scrapers/x/profile/posts" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: x-profile-posts-001" \
  -H "Prefer: respond-async" \
  --data '{"profiles":["nasa"],"limit":2}'

{
  "profiles": [
    "nasa"
  ],
  "limit": 2
}

{
  "job_id": "rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service": "x",
  "operation": "profile/posts",
  "status": "pending",
  "created_at": 1789913600,
  "expires_at": 1790000000,
  "poll_url": "/scrapers/jobs/rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "result": null,
  "error": null
}

{
  "items": [
    {
      "target": "nasa",
      "input_index": 0,
      "post_id": "123",
      "url": "https://x.com/nasa/status/123",
      "author": {
        "username": "nasa",
        "profile_url": "https://x.com/nasa"
      },
      "timestamp": "2026-09-01T12:00:00+00:00",
      "text": "Public post example.",
      "media": [],
      "geotag": null,
      "tagged_users": null,
      "mentions": null,
      "context": []
    }
  ],
  "count": 1,
  "result_id": "rresult_11111111111111111111111111111111",
  "page": 1,
  "limit": 2,
  "next_page": null,
  "collected_count": 1,
  "collection_limit": 500,
  "expires_at": 1790000000,
  "truncated": null,
  "partial": false,
  "targets": [
    {
      "target": "nasa",
      "input_index": 0,
      "status": "resolved",
      "collected_count": 1,
      "reason": null
    }
  ],
  "unresolved": [],
  "per_target_limit": 50,
  "history_complete": null
}

{
  "Idempotency-Key": "x-people-search-001",
  "Prefer": "respond-async"
}

curl --fail-with-body --max-time 30 -sS "https://hive-osint-dev.172-86-73-30.sslip.io/scrapers/x/people/search" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: x-people-search-001" \
  -H "Prefer: respond-async" \
  --data '{"query":"José García","locations":["Madrid"],"limit":2}'

{
  "query": "José García",
  "locations": [
    "Madrid"
  ],
  "limit": 2
}

{
  "job_id": "rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service": "x",
  "operation": "people/search",
  "status": "pending",
  "created_at": 1789905600,
  "expires_at": 1789992000,
  "poll_url": "/scrapers/jobs/rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "result": null,
  "error": null
}

{
  "items": [
    {
      "query": "José García",
      "rank": 1,
      "status": "candidate",
      "username": "example_person",
      "profile_url": "https://x.com/example_person",
      "profile_id": "123456",
      "display_name": "José García",
      "biography": "Synthetic public biography",
      "image_url": "https://images.example.com/avatar.jpg",
      "missing_fields": [],
      "location": "Madrid"
    }
  ],
  "count": 1,
  "result_id": "rresult_22222222222222222222222222222222",
  "page": 1,
  "limit": 2,
  "next_page": null,
  "collected_count": 1,
  "collection_limit": 50,
  "expires_at": 1789992000,
  "truncated": null,
  "partial": false,
  "query": "José García",
  "locations": [
    "Madrid"
  ],
  "effective_query": "José García Madrid",
  "location_handling": "query_hint",
  "filters_enforced": false
}

{
  "profiles": [
    "nasa"
  ]
}

{
  "items": [
    {
      "username": "nasa",
      "profile_url": "https://www.facebook.com/NASA",
      "display_name": "NASA",
      "target": "nasa",
      "input_index": 0
    }
  ],
  "count": 1,
  "unresolved": []
}

{
  "Idempotency-Key": "facebook-profile-posts-001",
  "Prefer": "respond-async"
}

curl --fail-with-body --max-time 30 -sS "https://hive-osint-dev.172-86-73-30.sslip.io/scrapers/facebook/profile/posts" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: facebook-profile-posts-001" \
  -H "Prefer: respond-async" \
  --data '{"profiles":["nasa"],"limit":2}'

{
  "profiles": [
    "nasa"
  ],
  "limit": 2
}

{
  "job_id": "rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service": "facebook",
  "operation": "profile/posts",
  "status": "pending",
  "created_at": 1789913600,
  "expires_at": 1790000000,
  "poll_url": "/scrapers/jobs/rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "result": null,
  "error": null
}

{
  "items": [
    {
      "target": "nasa",
      "input_index": 0,
      "post_id": "123",
      "url": "https://www.facebook.com/nasa/posts/123",
      "author": {
        "username": "nasa",
        "profile_url": "https://www.facebook.com/nasa"
      },
      "timestamp": "2026-09-01T12:00:00+00:00",
      "text": "Public post example.",
      "media": [],
      "geotag": null,
      "tagged_users": null,
      "mentions": null,
      "context": []
    }
  ],
  "count": 1,
  "result_id": "rresult_11111111111111111111111111111111",
  "page": 1,
  "limit": 2,
  "next_page": null,
  "collected_count": 1,
  "collection_limit": 500,
  "expires_at": 1790000000,
  "truncated": null,
  "partial": false,
  "targets": [
    {
      "target": "nasa",
      "input_index": 0,
      "status": "resolved",
      "collected_count": 1,
      "reason": null
    }
  ],
  "unresolved": [],
  "per_target_limit": 40,
  "history_complete": null,
  "history_scope": "recent_public_timeline"
}

{
  "Idempotency-Key": "facebook-people-search-001",
  "Prefer": "respond-async"
}

curl --fail-with-body --max-time 30 -sS "https://hive-osint-dev.172-86-73-30.sslip.io/scrapers/facebook/people/search" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: facebook-people-search-001" \
  -H "Prefer: respond-async" \
  --data '{"query":"José García","locations":["Madrid"],"limit":2}'

{
  "query": "José García",
  "locations": [
    "Madrid"
  ],
  "limit": 2
}

{
  "job_id": "rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service": "facebook",
  "operation": "people/search",
  "status": "pending",
  "created_at": 1789905600,
  "expires_at": 1789992000,
  "poll_url": "/scrapers/jobs/rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "result": null,
  "error": null
}

{
  "items": [
    {
      "query": "José García",
      "rank": 1,
      "status": "candidate",
      "username": null,
      "profile_url": "https://www.facebook.com/profile.php?id=123456",
      "profile_id": "123456",
      "display_name": "José García",
      "biography": null,
      "image_url": "https://images.example.com/avatar.jpg",
      "missing_fields": [
        "biography"
      ],
      "profile_type": "person",
      "location": "Madrid"
    }
  ],
  "count": 1,
  "result_id": "rresult_22222222222222222222222222222222",
  "page": 1,
  "limit": 2,
  "next_page": null,
  "collected_count": 1,
  "collection_limit": 50,
  "expires_at": 1789992000,
  "truncated": null,
  "partial": true,
  "query": "José García",
  "locations": [
    "Madrid"
  ],
  "effective_query": "José García Madrid",
  "location_handling": "query_hint",
  "filters_enforced": false
}

{
  "profiles": [
    "nasa"
  ]
}

{
  "items": [
    {
      "username": "nasa",
      "profile_url": "https://www.tiktok.com/@nasa",
      "display_name": "NASA",
      "target": "nasa",
      "input_index": 0
    }
  ],
  "count": 1,
  "unresolved": []
}

{
  "Idempotency-Key": "tiktok-profile-posts-001",
  "Prefer": "respond-async"
}

curl --fail-with-body --max-time 30 -sS "https://hive-osint-dev.172-86-73-30.sslip.io/scrapers/tiktok/profile/posts" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tiktok-profile-posts-001" \
  -H "Prefer: respond-async" \
  --data '{"profiles":["nasa"],"limit":2}'

{
  "profiles": [
    "nasa"
  ],
  "limit": 2
}

{
  "job_id": "rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service": "tiktok",
  "operation": "profile/posts",
  "status": "pending",
  "created_at": 1789913600,
  "expires_at": 1790000000,
  "poll_url": "/scrapers/jobs/rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "result": null,
  "error": null
}

{
  "items": [
    {
      "target": "nasa",
      "input_index": 0,
      "post_id": "123",
      "url": "https://www.tiktok.com/@nasa/video/123",
      "author": {
        "username": "nasa",
        "profile_url": "https://www.tiktok.com/@nasa"
      },
      "timestamp": "2026-09-01T12:00:00+00:00",
      "text": "Public post example.",
      "media": [],
      "geotag": null,
      "tagged_users": null,
      "mentions": null,
      "context": []
    }
  ],
  "count": 1,
  "result_id": "rresult_11111111111111111111111111111111",
  "page": 1,
  "limit": 2,
  "next_page": null,
  "collected_count": 1,
  "collection_limit": 500,
  "expires_at": 1790000000,
  "truncated": null,
  "partial": false,
  "targets": [
    {
      "target": "nasa",
      "input_index": 0,
      "status": "resolved",
      "collected_count": 1,
      "reason": null
    }
  ],
  "unresolved": [],
  "per_target_limit": 50,
  "history_complete": null,
  "history_scope": "collected_window"
}

{
  "Idempotency-Key": "tiktok-people-search-001",
  "Prefer": "respond-async"
}

curl --fail-with-body --max-time 30 -sS "https://hive-osint-dev.172-86-73-30.sslip.io/scrapers/tiktok/people/search" \
  -H "Authorization: Bearer $HIVE_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: tiktok-people-search-001" \
  -H "Prefer: respond-async" \
  --data '{"query":"José García","locations":["Madrid"],"limit":2}'

{
  "query": "José García",
  "locations": [
    "Madrid"
  ],
  "limit": 2
}

{
  "job_id": "rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "service": "tiktok",
  "operation": "people/search",
  "status": "pending",
  "created_at": 1789905600,
  "expires_at": 1789992000,
  "poll_url": "/scrapers/jobs/rjob_aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
  "result": null,
  "error": null
}

{
  "items": [
    {
      "query": "José García",
      "rank": 1,
      "status": "candidate",
      "username": "example_person",
      "profile_url": "https://www.tiktok.com/@example_person",
      "profile_id": "123456",
      "display_name": "José García",
      "biography": "Synthetic public biography",
      "image_url": "https://images.example.com/avatar.jpg",
      "missing_fields": []
    }
  ],
  "count": 1,
  "result_id": "rresult_22222222222222222222222222222222",
  "page": 1,
  "limit": 2,
  "next_page": null,
  "collected_count": 1,
  "collection_limit": 50,
  "expires_at": 1789992000,
  "truncated": null,
  "partial": false,
  "query": "José García",
  "locations": [
    "Madrid"
  ],
  "effective_query": "José García Madrid",
  "location_handling": "query_hint",
  "filters_enforced": false
}

{
  "usernames": [
    "nasa"
  ],
  "limit": 20
}

{
  "items": [
    {
      "username": "nasa",
      "site": "GitHub",
      "profile_url": "https://github.com/nasa",
      "status": "candidate"
    }
  ],
  "count": 1,
  "truncated": null
}

{
  "queries": [
    "site:nasa.gov Artemis"
  ],
  "limit": 20,
  "pages": 1,
  "country": "us",
  "language": "en"
}

{
  "items": [
    {
      "query": "site:nasa.gov Artemis",
      "rank": 1,
      "title": "Artemis",
      "url": "https://www.nasa.gov/artemis/",
      "snippet": "Explore the Artemis program."
    }
  ],
  "count": 1
}

{
  "image_url": "https://gpm.nasa.gov/sites/default/files/document_files/NASA-Logo-Large.png",
  "search_types": [
    "visual",
    "exact",
    "text"
  ],
  "limit": 20
}

{
  "items": [
    {
      "type": "visual",
      "title": "NASA",
      "url": "https://www.nasa.gov/"
    },
    {
      "type": "exact",
      "title": "NASA logo",
      "url": "https://www.nasa.gov/logos/"
    },
    {
      "type": "text",
      "text": "NASA"
    }
  ],
  "count": 3
}

Submit POST /books/queries, then poll the opaque query ID. Inspect results through GET /books/items/{book_id}. Submit POST /books/downloads, poll the download, and retrieve its artifact when ready.

Query and download submissions require an Idempotency-Key. Availability is reported separately in /capabilities; configuration alone does not establish a working download.

{
  "query": "Pride and Prejudice",
  "limit": 10
}

Use a returned book_id and one of its available formats in the download body: {"book_id":"<returned-book-id>","format":"epub"}.

Keep a connection open

Renew before lease_expires_at to keep using the same route and credentials. Browser sessions can run for up to one hour; max_expires_at gives the final deadline. Create a new session once the current one expires.

Change a tunnel’s IP address

Use rotate when you need a new exit IP. Hive checks the replacement against your requested country, region, ASN, and network type. If no matching replacement is available, your current connection stays in place.

Reuse a network identity

Pass the same identity_token to request a sticky allocation. A request that cannot preserve that identity fails rather than assigning a different one. Use mobile: true; non-mobile allocations are currently unavailable.

Connect securely

Browser WebSocket connections use your Hive bearer key. Proxy connections use the separate username and password returned when you create a tunnel. Save those credentials from the creation response.

SOCKS5 and HTTP proxy authentication travels unencrypted. HTTPS CONNECT encrypts traffic to the destination after the proxy handshake; it does not encrypt the proxy credentials.

400 invalid request · 401 invalid Hive authentication · 403 forbidden · 404 not found · 409 conflicting or expired state · 429 rate limited · 503 service or constraints unavailable · 504 timeout.

Errors expose stable error codes. Do not blindly retry allocations or timed-out research calls. Reuse an idempotency key where supported, and inspect an existing resource before creating another.