How to Migrate from Diffbot to AlterLab: Step-by-Step Guide (2026)

Both APIs are capable — this guide is for developers prioritizing pay-as-you-go pricing and no subscription requirements.

TL;DR

To migrate from Diffbot to AlterLab, sign up for a free AlterLab account, install the AlterLab SDK, replace your Diffbot client calls with alterlab.Client, and update your API key. The response format is largely compatible, so most of your existing code works unchanged.

Why migrate?

Diffbot's enterprise pricing includes knowledge graph add-ons and requires a $300+/month commitment. AlterLab offers a pure pay-as-you-go model with no subscription, so you only pay for what you use and your balance never expires.

Prerequisites

• An AlterLab account (create one for free at /signup)
• Your AlterLab API key (found in the dashboard after signup)
• About five minutes of time

Step 1: Install the AlterLab SDK

If you prefer using the official Python SDK, run the installation command. You can also call the REST API directly if you avoid SDKs.

pip install alterlab

For full setup instructions, see the getting started guide.

Step 2: Replace your API calls

Below is a side‑by‑side comparison of typical Diffbot usage and the equivalent AlterLab call. The structure is intentionally similar to minimize changes.

# Diffbot (before migration)
from diffbot import DiffbotClient

client = DiffbotClient("YOUR_DIFFBOT_TOKEN")
response = client.article(url="https://example.com/news")
print(response.text)

# AlterLab (after migration)
import alterlab

client = alterlab.Client("YOUR_ALTERLAB_API_KEY")
response = client.scrape("https://example.com/news")
print(response.text)  # Same accessible field, pay‑as‑you‑go pricing

If you were using Diffbot’s automatic article extraction, AlterLab provides the same raw HTML and text fields. For structured data you can add the Cortex AI parameter (formats=['json']) or use the built‑in extraction endpoints.

Step 3: Handle response format differences

AlterLab returns a JSON object with text, html, and optionally json keys when you request specific formats. Diffbot’s article response nests fields under objects like objects[0].text. In practice, you can access the plain text via response.text in both libraries after the minor SDK change shown above. If you relied on Diffbot’s metadata (such as author or date), you can enable AlterLab’s Cortex AI extraction to receive a structured JSON payload that includes those fields.

Step 4: Update your error handling

Both services use standard HTTP status codes. AlterLab returns:

• 429 when you exceed your rate limit (same as Diffbot)
• 401 for invalid API keys
• 5xx for transient server issues

Your existing retry logic based on status codes will continue to work. If you currently parse Diffbot‑specific error messages, replace those checks with the standard HTTP code handling.

Cost comparison

Diffbot’s published pricing requires a minimum monthly commitment — their entry plan starts at $299 per month for access to the APIs, which effectively raises the cost per request if you do not reach high volume. AlterLab charges $0.0002 per request with no monthly minimum and your balance never expires.

For a concrete example, consider 10,000 requests:

• AlterLab: 10,000 × $0.0002 = $2.00
• Diffbot: You would still pay the $299 monthly minimum unless your usage qualifies for a higher‑tier plan, making the effective cost per request far higher at low volumes.

See the latest details on the AlterLab pricing page.

Common issues and fixes

• Missing API key – Double‑check that you placed the AlterLab key in your environment variable or config file; the SDK raises a 401 error if the key is absent.
• Format expectations – If you expected Diffbot’s wrapped object structure, access response.text directly or add formats=['json'] to receive a JSON payload similar to Diffbot’s output.
• Rate‑limit handling – AlterLab uses the same 429 response; ensure your retry‑after header logic is intact.
• Cortex AI extraction – For article‑level metadata, enable the Cortex AI add‑on in your request; otherwise you receive raw HTML and text only.

You're done

Your migration is complete. Run your test suite to confirm everything works as expected. For more details on advanced features like scheduling, webhooks, or team accounts, refer to the full documentation.