RolesAPI documentation

RolesAPI is a REST API for Indeed job-postings data. You send one HTTP request with a Bearer key; you get back a normalized JSON role object — title, company, location, salary, benefits, description — inside a consistent envelope. No browser automation, no parsing, no infrastructure to run.

All requests go to a single base URL:

https://api.rolesapi.com

What does a call look like?

curl "https://api.rolesapi.com/v1/roles/by-url?url=https://www.indeed.com/viewjob?jk=a1b2c3d4e5f60718" \
  -H "Authorization: Bearer rk_live_your_key"

{
  "data": {
    "job_key": "a1b2c3d4e5f60718",
    "title": "Senior Backend Engineer",
    "company": { "name": "Acme Logistics", "rating": 4.1, "url": "https://www.indeed.com/cmp/Acme-Logistics" },
    "location": "Austin, TX",
    "remote": false,
    "employment_type": "Full-time",
    "salary": { "min": 140000, "max": 175000, "currency": "USD", "period": "year", "source": "employer" },
    "benefits": ["Health insurance", "401(k) matching", "Paid time off"],
    "description": "Acme Logistics is hiring a Senior Backend Engineer to build the services that power our fulfillment network...",
    "posted_at": "2026-06-28",
    "url": "https://www.indeed.com/viewjob?jk=a1b2c3d4e5f60718",
    "country": "us"
  },
  "request_id": "req_8f3a2b1c"
}

That call costs 1 credit. Every plan includes 100 free credits — no card required.

Where should I start?

• Quickstart — make your first call in under five minutes.
• Authentication — create and manage rk_ API keys.
• Errors — the error envelope and every error code.
• Rate limits — per-plan requests-per-minute and how to handle 429s.

API reference

• Roles — fetch a single role by URL or job key, plus batch retrieval.
• Search — keyword and location search, with optional full details.
• Listings — curated lists: posted today, posted this week, remote.
• Jobs — poll async jobs and page through results.
• Webhooks — get notified when async jobs finish.
• Account — plan, credits remaining, and usage records.

Guides and recipes

• Async jobs — how batch and multi-page work runs in the background.
• Output formats — JSON, CSV, and NDJSON on any results endpoint.
• Field projection — trim responses to just the fields you need.
• Search then detail — a runnable Python pipeline.
• Export to Google Sheets — three ways to land jobs in a sheet.
• AI agents — connect Claude, Cursor, and other agents over MCP.

Coverage

RolesAPI covers 60+ Indeed country editions. Pass country=de, country=gb, or any other edition code on role and search endpoints; the default is us.