Cyclosa web scraping service logoCyclosa
HOW IT WORKSSERVICESHOW IT WORKSPRICINGABOUTBLOG
LOG INGET STARTED
API DOCUMENTATION

Put Cyclosa inside your own stack.

Send a list of URLs, get back the contacts found on them, and have every finished batch pushed straight to your CRM. Bearer-token auth, signed webhooks, and the same credit your console spends.

ON THIS PAGE
Field reference

Every request and response field, generated from the endpoints themselves so it cannot drift.

OPEN THE REFERENCE →

Overview

Send us a list of URLs; get back the emails, phone numbers and social profiles found on them. Everything the console does, your own systems can do — which is how a scrape reaches your CRM without anyone exporting a spreadsheet.

REST over HTTPS, JSON in and out. Every URL spends credit from the same balance the console spends, at your plan's published rate.

Base URL   https://api.cyclosa.co/api/public
Auth       Authorization: Bearer cyc_live_…
Versioning /v1 is in the path, so a URL says which contract it was written against

New optional fields can appear inside v1, so parse defensively and ignore what you do not recognise. Anything that would break a working integration opens a v2 served alongside it.

Authentication

Create a key in the console under Developers, and send it on every request:

Authorization: Bearer cyc_live_xxxxxxxxxxxxxxxxxxxx

A key is shown once, when you create it. We store only a hash, so we cannot show it again and neither can anyone who reaches our database — a lost key is replaced, not recovered.

Send it as a header and never in a query string, which is written to the logs of every proxy between you and us.

An account has one key at a time. Creating a key retires the previous one the moment it is issued, so a token you have stopped trusting is dead as soon as its replacement exists — there is no second credential left open for someone to find later.

That also means replacing a key is a change you deploy: every system sending the old one starts getting 401 at once. Work already queued is unaffected — a key authorises the submission, not the batch, so scrapes in flight finish normally and their contacts stay readable with the new key.

Quickstart

Three calls, or two if you use a webhook: send the URLs, wait for the batch to finish, then read the contacts off it.

export CYCLOSA_KEY=cyc_live_…

# 1. Send the URLs
BATCH=$(curl -sS -X POST https://api.cyclosa.co/api/public/v1/scrapes \
  -H "Authorization: Bearer $CYCLOSA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls":["https://acme.example/contact"]}' | jq -r .batch_id)

# 2. Wait for it
until [ "$(curl -sS https://api.cyclosa.co/api/public/v1/scrapes/$BATCH \
  -H "Authorization: Bearer $CYCLOSA_KEY" | jq -r .status)" = finished ]; do
  sleep 3
done

# 3. Take the contacts
curl -sS https://api.cyclosa.co/api/public/v1/scrapes/$BATCH/contacts \
  -H "Authorization: Bearer $CYCLOSA_KEY"

There is no SDK to install: these are the standard HTTP client and JSON parser your language already ships, which is one fewer dependency to keep current.

Submit URLs

POST /v1/scrapes answers 202, not 200 — the work is accepted, not done. A browser render takes seconds and a challenged page tens of them, so the contacts arrive later.

urlsstring[]Required. 1 to 500 absolute URLs.
namestringWhat to call the batch. Defaults to a count.
renderbooleanDraw the page in a browser first, for sites that write their contacts with JavaScript. Costs more credit.
llmbooleanRead the page with a model rather than with patterns. Finds details that are written out rather than marked up. Costs more credit.
refreshbooleanFetch again even if the page was scraped recently. Off by default, so a repeat inside the cache window is free.
curl -X POST https://api.cyclosa.co/api/public/v1/scrapes \
  -H "Authorization: Bearer $CYCLOSA_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://acme.example/contact", "https://globex.example"],
    "name": "Tuesday prospects",
    "render": false,
    "llm": false
  }'
{
  "batch_id": "6f1c2d…",
  "accepted": 2,
  "queued": [{"url": "https://acme.example/contact", "job_id": "…", "state": "queued"}],
  "cached": [{"url": "https://globex.example", "job_id": "…", "state": "cached"}],
  "render": false,
  "llm": false
}

A URL someone scraped recently comes back under cached and is already complete — it cost no credit and will not be fetched. Set refresh: true to fetch it anyway.

A submission you cannot afford is refused whole, with a 402. Nothing is queued and no batch is created, so there is never a half-started list to clean up.

Check progress

GET /v1/scrapes/{batch_id} is cheap enough to poll every few seconds.

statusstringrunning, or finished when nothing more is coming.
total_urlsintegerHow many URLs were accepted.
doneintegerRead successfully.
failedintegerCould not be read. Counts toward finished.
runningintegerBeing fetched right now.
queuedintegerWaiting for a slot.
contacts_foundintegerContacts across the whole batch so far.
{"batch_id": "6f1c2d…", "status": "running", "total_urls": 2,
 "done": 1, "failed": 0, "running": 1, "queued": 0, "contacts_found": 3}

finished means nothing more is coming, which includes the URLs that could not be read. Check failed rather than waiting for done to reach total_urls — that will not happen if one site timed out, and some always do.

Read the contacts

GET /v1/scrapes/{batch_id}/contacts answers while the batch is still running as well as after it finishes, so a long list can be drained as it completes.

urlstringThe URL you sent.
final_urlstring | nullWhere it ended up after redirects.
statusstringqueued, running, done or failed.
http_statusinteger | nullWhat the site answered.
titlestring | nullThe page title, when it had one.
contacts.emailsstring[]Addresses found on the page.
contacts.phonesstring[]Numbers, cleaned to E.164 where possible.
contacts.socialstring[]Profile URLs.
cachedbooleanAnswered from an earlier scrape rather than fetched.
errorstring | nullWhy it failed, when it did.
{
  "batch_id": "6f1c2d…",
  "status": "finished",
  "total_urls": 2,
  "results": [
    {
      "url": "https://acme.example/contact",
      "final_url": "https://acme.example/contact",
      "status": "done",
      "http_status": 200,
      "title": "Contact us — Acme",
      "contacts": {
        "emails": ["sales@acme.example"],
        "phones": ["+63 2 8123 4567"],
        "social": ["https://linkedin.com/company/acme"]
      },
      "cached": false,
      "error": null
    }
  ]
}

Credit and limits

GET /v1/account says what you have left. Worth asking before a long list, because a submission beyond your credit is refused rather than trimmed.

{"plan": "pro", "scans_left": 14300, "included_scans": 15000,
 "concurrency": 5, "in_flight": 1}

concurrency is how many URLs your plan fetches at once. Submitting while every slot is busy answers 429 — wait for one to finish, or move to a plan with more. Jobs from paid plans are handed out ahead of Free ones. There is no separate request-rate limit: credit and concurrency are what bound the work.

Webhooks

Register a URL and we post each finished batch to it, contacts included. Nothing on your side has to run a timer, and a CRM sync becomes a handler rather than a cron job.

curl -X PUT https://api.cyclosa.co/api/public/v1/webhook \
  -H "Authorization: Bearer $CYCLOSA_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://your-crm.example/hooks/cyclosa"}'

{"url": "https://your-crm.example/hooks/cyclosa", "secret": "shown once"}

The secret comes back here and from POST /v1/webhook/rotate, and nowhere else. Setting the same URL again keeps it, so correcting a typo does not break a receiver that was verifying properly.

Each delivery arrives as:

POST https://your-crm.example/hooks/cyclosa
X-Cyclosa-Event: batch.finished
X-Cyclosa-Delivery: 1841
X-Cyclosa-Signature: sha256=…

{
  "event": "batch.finished",
  "batch": {"id": "6f1c2d…", "name": "Tuesday prospects", "total_urls": 2,
            "created_at": "2026-09-22T20:31:02+00:00"},
  "results": [ … the same shape as /contacts … ]
}

The contacts are in the payload rather than behind a link, so the thing receiving it does not need an API key of its own.

Verifying a delivery

Anyone who learns your URL can post to it. The signature is what says we sent it, so check it before you trust the body.

import hmac, hashlib

def is_ours(raw_body: bytes, header: str, secret: str) -> bool:
    expected = hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(header, f"sha256={expected}")

Compute it over the exact bytes you received, not over a re-encoded copy of the parsed JSON. Two encoders disagree about spacing and key order, and a signature over a different rendering of the same data fails for no reason you can see. Most frameworks need telling to keep the raw body.

Retries and failures

Answer 2xx, and answer quickly — queue the work on your side rather than doing it while we wait. We give up on a response after 10 seconds.

Anything else is retried after 1 minute, then 5, 30, 120, 480 and 1440. After the sixth attempt we stop; the batch is still there to fetch over the API, and GET /v1/webhook/deliveries shows what happened, with the status code and error we saw.

Delivery is at-least-once. A receiver that times out after acting on a payload will be sent it again, so key on batch.id and a repeat costs you nothing.

Errors

Every error is JSON with a detail naming what went wrong in words you can show someone.

401The key is missing, malformed, unknown or revoked.
402Not enough credit for the URLs in this request. Nothing was queued.
404No such batch — or it belongs to another account.
422The body did not validate. The response names the field.
429Every concurrent slot your plan sells is already busy.
503The queue is not accepting work. Retry shortly.

Every endpoint

POST/v1/scrapesQueue a list of URLs
GET/v1/scrapesRecent batches, newest first
GET/v1/scrapes/{batch_id}How far along one is
GET/v1/scrapes/{batch_id}/contactsWhat was found
GET/v1/accountCredit and concurrency left
PUT/v1/webhookSet where batches are delivered
GET/v1/webhookWhere they go now
POST/v1/webhook/rotateReplace the signing secret
DELETE/v1/webhookStop delivering
GET/v1/webhook/deliveriesWhat was sent, and what came back

Request and response fields for each are on the generated reference, where you can also try them with your own key.

Ready to connect something? Keys live in the console.CREATE AN API KEYFree plans included.