The Tadaaah API

Why people use it

• One site or many — POST a single URL, or up to 50 per request and poll the whole batch at once.
• Cheap re-audits — repeat domains are served from cache instantly and don't count against your quota.
• Confidence per metric — every score is measured, AI estimate, or estimated, so you know what's externally verifiable.
• CSV export — drop a whole batch straight into a spreadsheet, report, or dashboard.

Authentication

Every request needs your API key in the X-API-Key header (or Authorization: Bearer <key>). PRO subscribers generate a key in one click from the dashboard (100 audits / rolling 30 days). Agencies needing higher volume — contact us for a larger key.

curl https://tadaaah.io/v1/me \
  -H "X-API-Key: tdh_live_your_key_here"

Usage is metered on a rolling 30-day window. Responses include X-RateLimit-Limit and X-RateLimit-Remaining.

Submit a batch

Send one url or many urls (max 50). Optional lang (en/fr) sets the language of the written summary.

curl -X POST https://tadaaah.io/v1/audits \
  -H "X-API-Key: tdh_live_your_key_here" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://acme.com", "https://beta-client.io"], "lang": "en"}'

Returns 202 with a batch id and one entry per URL. Cached URLs come back done immediately; the rest are pending.

{
  "success": true,
  "batch_id": "9f8c2a...",
  "count": 2,
  "metered": 1,
  "audits": [
    { "url": "https://acme.com",       "audit_id": "a1b2...", "status": "done",    "cached": true  },
    { "url": "https://beta-client.io", "audit_id": "c3d4...", "status": "pending", "cached": false }
  ],
  "quota": { "limit": 5000, "remaining": 4712, "window": "rolling 30 days" }
}

Poll the batch

Returns every audit's current status; completed ones include the full scored result. Poll every few seconds until pending reaches 0.

{
  "success": true,
  "batch_id": "9f8c2a...",
  "total": 2, "completed": 1, "pending": 1,
  "audits": [
    {
      "url": "https://acme.com",
      "status": "done",
      "overall_ai_readiness": 78,
      "scores": {
        "ai_readiness":    { "value": 78, "tier": "ai_estimate", "source": "AI estimate — Tadaaah blended model" },
        "seo":             { "value": 84, "tier": "measured",    "source": "Measured — on-page analysis" },
        "ai_crawlability": { "value": 92, "tier": "measured",    "source": "Measured — raw HTML (no-JS bot view)" },
        "performance":     { "value": 53, "tier": "measured",    "source": "Measured — Google Lighthouse (PageSpeed)" }
      },
      "business": { "industry": "Plumbing", "type": "Local service" },
      "summary": "Acme's site is fast for crawlers but ..."
    }
  ]
}

Single audit

Fetch one audit on its own — same shape as a batch entry.

CSV export

The whole batch as a flat CSV — one row per URL, a column per metric — ready to paste into a client report or a Google Sheet.

curl https://tadaaah.io/v1/batches/9f8c2a....csv \
  -H "X-API-Key: tdh_live_your_key_here" -o audits.csv

Confidence tiers

Mirroring what tadaaah.io shows on every score card, so you can tell clients exactly which numbers are directly verifiable:

Tier	Means	Examples
measured	Read from the live page or a real external tool — externally verifiable.	SEO, AI crawlability, performance (PageSpeed), security (TLS)
ai_estimate	Tadaaah's model judgement.	GEO, AEO, GSO, design, overall AI readiness
estimated	Proxy signals, not a direct measurement.	Local visibility, performance when PageSpeed is unavailable