Listings

The listings endpoints answer the common “what is out there right now” questions without you composing search filters. One GET endpoint for quick summary lists, and three POST presets that run recency- and remote-filtered collection as async jobs.

Method	Path	What it returns	Mode
GET	/v1/listings	A page of role summaries	Sync
POST	/v1/listings/posted-today	Roles posted in the last day	Async
POST	/v1/listings/posted-this-week	Roles posted in the last seven days	Async
POST	/v1/listings/remote	Remote roles matching the keyword	Async

curl "https://api.rolesapi.com/v1/listings?keyword=backend+engineer&location=Austin,+TX&sort=date" \
  -H "Authorization: Bearer rk_live_your_key"

GET /v1/listings

A synchronous page of role summaries — the lightest way to show current postings in a UI.

Parameter	In	Type	Required	Description
keyword	query	string	Yes	Search terms.
location	query	string	No	City, state, or region.
country	query	string	No	Country edition code. Default us.
sort	query	string	No	date or relevance. Default relevance.

Credits: 1 per page (this endpoint returns one page).

{
  "data": [
    {
      "job_key": "a1b2c3d4e5f60718",
      "title": "Senior Backend Engineer",
      "company": { "name": "Acme Logistics", "rating": 4.1 },
      "location": "Austin, TX",
      "remote": false,
      "posted_at": "2026-06-28",
      "url": "https://www.indeed.com/viewjob?jk=a1b2c3d4e5f60718",
      "country": "us"
    }
  ],
  "meta": { "total": 18, "count": 18, "limit": 18, "offset": 0, "has_more": false },
  "request_id": "req_5e77ab90"
}

What do the POST presets take?

All three presets share one body:

Parameter	Type	Required	Description
keyword	string	Yes	Search terms.
location	string	No	City, state, or region. Ignored by /remote in the usual case.
country	string	No	Country edition code. Default us.
max_pages	integer	No	1–3 pages to collect. Default 1.

Credits: 1 per page collected. Each preset responds synchronously with the filtered rows:

curl -X POST "https://api.rolesapi.com/v1/listings/posted-this-week" \
  -H "Authorization: Bearer rk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "backend engineer", "location": "Austin, TX", "max_pages": 3}'

{
  "data": [ { "job_key": "a1b2c3d4e5f60718", "title": "Backend Engineer", "...": "..." } ],
  "meta": { "count": 14, "pages_fetched": 3 },
  "request_id": "req_90c1e2f4"
}

The remote preset works the same way:

curl -X POST "https://api.rolesapi.com/v1/listings/remote" \
  -H "Authorization: Bearer rk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"keyword": "backend engineer", "country": "us", "max_pages": 2}'

Errors: 400 invalid_request if keyword is missing or max_pages is outside 1–3; 402 out_of_credits on a zero balance.

When should I prefer listings over search?

• You want a time or remote filter, not a query language. The presets encode “today,” “this week,” and “remote” so you do not maintain filter logic.
• You are building recurring alerts. A weekly scheduled posted-this-week call is a complete alert pipeline — see Job alerts with n8n or Zapier.
• You need one fast page for a UI. GET /v1/listings is a single synchronous call.

Prefer Search when you need sort control across many pages of arbitrary queries, or full role details in one operation via with-details.