Skip to content
PT Start free

// docs

Catho: Search jobs

Extracts job listing (PLP) from Catho with filters and pagination.

catho.com.br:plp · 1 credit per request

Standard credit cost. Your account pricing is shown in the sandbox.

Try this operation in the sandbox

HTTP request

cURL 
curl -X POST https://api.geckoapi.com.br/v1/extract \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "target": "catho.com.br",
  "type": "plp",
  "jobTitle": "desenvolvedor",
  "city": "Sao Paulo",
  "state": "SP",
  "workModel": [
    "remote",
    "hybrid"
  ],
  "page": 2
}'

Keep your API key on your server. See the quickstart for authentication and response handling.

MCP request

The hosted MCP tool fixes target and type for this operation. Its remaining arguments use the same input rules as Extract.

POST /v1/mcp · Bearer or X-API-Key authentication

catho_com_br_plp · tools/call 
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "catho_com_br_plp",
    "arguments": {
      "jobTitle": "desenvolvedor",
      "city": "Sao Paulo",
      "state": "SP",
      "workModel": [
        "remote",
        "hybrid"
      ],
      "page": 2,
      "executionId": "exec_example_123"
    }
  }
}

Supported inputs

Conditional fields depend on the alternatives and constraints in the rule column. Fields marked unsupported are omitted.

FieldTypeRequirementRuleDefaultExample
url
URL extraction target. For some PLPs it can be omitted when API assembles URL from other fields.
 string (URL) Conditional Optional; when absent there should be jobTitle (or keyword). - https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?page=2&work_model[0]=remote
keyword
Keyword for PLP searches. In Google Search it represents the query sent to Google; in Booking PLP is mandatory; in other PLPs it can replace URL.
 string Conditional Accepted as an alternative to jobTitle when url is not sent. - iphone 15 pro max
jobTitle
Title/position for job searches (e.g.: Catho and Glassdoor) when URL is not sent.
 string Conditional Mandatory when url is not sent, unless keyword is used. - desenvolvedor
city
City used in structured searches for properties and vehicles and optionally in Catho PLP. In VivaReal, it requires state.
 string Conditional Optional, but if specified requires state. - Sao Paulo
state
UF used in structured searches for properties and vehicles and optionally in Catho PLP.
 string (UF 2 letters) Conditional Optional, but if specified requires city. - SP
workModel
Job template filter on Catho PLP.
 array<"remote" | "hybrid" | "presential"> Optional Optional for job template filter. - ["remote","hybrid"]
target
Target source for extraction.
 enum Required Always mandatory in the payload and must match the operation. - catho.com.br
type
Extraction type: pdp, idp, plp, ilp, quote, review or places.
 enum Required Always mandatory in the payload and must match the operation. - plp
page
Pagination. In PLP, including Trivago, and in Reclame AQUI ILP starts in 1; in review (MercadoLivre, Booking and Hotels) starts in 0. The Reclame AQUI ILP even accepts the page 100.
 integer Optional Supported for PLP; must be integer >= 1. - 2

Request examples

PLP by jobTitle/city/state

Job search with structured filters (without URL).

PLP by jobTitle/city/state 
{
  "target": "catho.com.br",
  "type": "plp",
  "jobTitle": "desenvolvedor",
  "city": "Sao Paulo",
  "state": "SP",
  "workModel": [
    "remote",
    "hybrid"
  ],
  "page": 2
}

PLP by URL

When URL is shipped, filters may be optional.

PLP by URL 
{
  "url": "https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?page=2&work_model[0]=remote",
  "target": "catho.com.br",
  "type": "plp"
}

Response schema

Leaf paths and expected types. Field names and enum values are part of the API contract.

responseSchema 
{
  "requestId": "string (uuid)",
  "executionId": "string (uuid)",
  "notFound": "boolean (optional; true when the upstream entity was not found and data is null)",
  "data.source": "string",
  "data.type": "string",
  "data.url": "string",
  "data.requestUrl": "string",
  "data.extractedAt": "string (iso datetime)",
  "data.query.jobTitle": "string",
  "data.query.city": "string",
  "data.query.state": "string",
  "data.query.workModel[]": "string",
  "data.query.page": "number",
  "data.totalResults": "number",
  "data.totalJobAds": "number",
  "data.page": "number",
  "data.resultsPerPage": "number",
  "data.nextPage": "number",
  "data.nextPageUrl": "string",
  "data.items[].id": "number",
  "data.items[].url": "string",
  "data.items[].title": "string",
  "data.items[].description": "string",
  "data.items[].benefits[]": "string",
  "data.items[].salary.min": "number",
  "data.items[].salary.max": "number",
  "data.items[].jobLocation": "string",
  "data.items[].employmentType": "string",
  "data.items[].hiringOrganization": "string",
  "data.items[].datePublished": "string",
  "data.items[].workSchedule": "string",
  "data.items[].active": "boolean",
  "data.items[].score": "number"
}

Example response

Illustrative response. Product names, reviews and other source content retain their original language. Missing and null values do not imply zero stock, free shipping or zero reviews.

responseExample 
{
  "requestId": "bbbbbbbb-1111-4111-8111-bbbbbbbbbbbb",
  "executionId": "bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb",
  "data": {
    "source": "catho.com.br",
    "type": "jlp",
    "url": "https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?work_model[0]=remote",
    "requestUrl": "https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?work_model[0]=remote",
    "extractedAt": "2026-02-12T21:20:00.000Z",
    "query": {
      "jobTitle": "desenvolvedor",
      "city": "Sao Paulo",
      "state": "SP",
      "workModel": [
        "remote",
        "hybrid"
      ],
      "page": 2
    },
    "totalResults": 9027,
    "totalJobAds": 960,
    "page": 2,
    "resultsPerPage": 15,
    "nextPage": 3,
    "nextPageUrl": "https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?page=3&work_model[0]=remote&work_model[1]=hybrid",
    "items": [
      {
        "id": 35324036,
        "url": "https://www.catho.com.br/vagas/desenvolvedor/35324036/",
        "title": "Desenvolvedor Backend Node.js",
        "description": "Atuacao em APIs, mensageria e arquitetura em nuvem.",
        "benefits": [
          "Vale Alimentacao",
          "Plano de Saude"
        ],
        "salary": {
          "min": 8000,
          "max": 12000
        },
        "jobLocation": "Sao Paulo - SP",
        "employmentType": "Prestador de servicos (PJ)",
        "hiringOrganization": "HRSOUL",
        "datePublished": "2026-02-10T23:59:59.000Z",
        "workSchedule": "Periodo Integral",
        "active": true,
        "score": 0.92
      }
    ]
  }
}

Complete field reference

PathTypeDescriptionExample
data.extractedAt string (iso datetime) data.extractedAt field returned in the response payload. 2026-02-12T21:20:00.000Z
data.items[].active boolean Field data.items[].active returned in the response payload. true
data.items[].benefits[] string Field data.items[].benefits[] returned in the response payload. Vale Alimentacao
data.items[].datePublished string Field data.items[].datePublished returned in the response payload. 2026-02-10T23:59:59.000Z
data.items[].description string Field data.items[].description returned in the response payload. Atuacao em APIs, mensageria e arquitetura em nuvem.
data.items[].employmentType string Field data.items[].employmentType returned in the response payload. Prestador de servicos (PJ)
data.items[].hiringOrganization string data.items[].hiringOrganization field returned in the response payload. HRSOUL
data.items[].id number Field data.items[].id returned in the response payload. 35324036
data.items[].jobLocation string data.items[].jobLocation field returned in the response payload. Sao Paulo - SP
data.items[].salary.max number Field data.items[].salary.max returned in the response payload. 12000
data.items[].salary.min number Field data.items[].salary.min returned in the response payload. 8000
data.items[].score number Field data.items[].score returned in the response payload. 0.92
data.items[].title string Field data.items[].title returned in the response payload. Desenvolvedor Backend Node.js
data.items[].url string data.items[].url field returned in the response payload. https://www.catho.com.br/vagas/desenvolvedor/35324036/
data.items[].workSchedule string Field data.items[].workSchedule returned in the response payload. Periodo Integral
data.nextPage number Field data.nextPage returned in the response payload. 3
data.nextPageUrl string Field data.nextPageUrl returned in the response payload. https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?page=3&work_model[0]=remote&work_model[1]=hybrid
data.page number Field data.page returned in the response payload. 2
data.query.city string data.query.city field returned in the response payload. Sao Paulo
data.query.jobTitle string Field data.query.jobTitle returned in the response payload. desenvolvedor
data.query.page number Field data.query.page returned in the response payload. 2
data.query.state string Field data.query.state returned in the response payload. SP
data.query.workModel[] string Field data.query.workModel[] returned in the response payload. remote
data.requestUrl string Same value as `data.url`; never exposes the queried internal endpoint. https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?work_model[0]=remote
data.resultsPerPage number Field data.resultsPerPage returned in the response payload. 15
data.source string Field data.source returned in the response payload. catho.com.br
data.totalJobAds number Field data.totalJobAds returned in the response payload. 960
data.totalResults number Field data.totalResults returned in the response payload. 9027
data.type string Field data.type returned in the response payload. jlp
data.url string Field data.url returned in the response payload. https://www.catho.com.br/vagas/desenvolvedor/sao-paulo-sp/?work_model[0]=remote
executionId string (uuid) Field executionId returned in the response payload. bbbbbbbb-2222-4222-8222-bbbbbbbbbbbb
notFound boolean (optional; true when the upstream entity was not found and data is null) Present and true when the upstream entity was not found. In this case data is null and the request still completes successfully. N/A
requestId string (uuid) Field requestId returned in the response payload. bbbbbbbb-1111-4111-8111-bbbbbbbbbbbb

Errors and missing data

When supported by this operation, an entity not found upstream can return HTTP 200 with data: null and notFound: true. Check the documented response fields before interpreting an empty result. Source-specific behavior and exceptions are described above.

HTTP statusError codeMeaning
400INVALID_PAYLOADInvalid JSON or a request that violates the documented validation rules.
401UNAUTHORIZEDMissing authorization or an invalid API key or token.
402INSUFFICIENT_CREDITSThe account has insufficient credits for this operation.
403FORBIDDENThe account does not have access, or the API is temporarily disabled.
409EXECUTION_CONFLICTThe execution identifier conflicts with an incompatible execution state.
429RATE_LIMIT_EXCEEDED / TOO_MANY_INFLIGHT_REQUESTSA rate limit or simultaneous request limit was exceeded.
5xxUPSTREAM_TIMEOUT / UPSTREAM_HTTP_ERROR / WORKER_FUNCTION_ERRORAn upstream, worker or gateway failure. Failed requests follow the platform refund policy.

Other Catho operations