# Gupy Scraper (`automation-lab/gupy-jobs-scraper`) Actor

Search and extract public Gupy jobs with company IDs, descriptions, locations, workplace models, dates, deadlines, and canonical application URLs.

- **URL**: https://apify.com/automation-lab/gupy-jobs-scraper.md
- **Developed by:** [Stas Persiianenko](https://apify.com/automation-lab) (community)
- **Categories:** Jobs
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

Pay per event

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Gupy Scraper

Search and extract public **Gupy** job listings as structured records for recruiting research, Brazilian labor-market analysis, job-board feeds, and hiring-signal monitoring.

The Actor queries Gupy's public jobs surface directly. It returns stable job and company IDs, titles, full cleaned descriptions, locations, workplace models, publication dates, deadlines, and canonical application URLs without requiring a candidate login.

### What does Gupy Scraper do?

Gupy Scraper turns public listings from Gupy-powered employer career pages into a consistent Apify dataset.

You can:

- search by job keyword;
- select one exact company career-page name;
- filter remote, hybrid, or on-site work;
- sort by newest publication date or relevance;
- collect up to 10,000 records per run;
- retain raw description HTML when your downstream parser needs it;
- schedule runs and compare stable `jobId` values over time.

The Actor uses a lightweight JSON route instead of loading browser pages. This keeps runs fast and avoids charging you for an unnecessary browser or residential proxy.

### Who is it for?

- **Recruiting and talent intelligence teams** tracking which employers are hiring.
- **Labor-market researchers** measuring job demand in Brazil.
- **Job-board operators** building a structured feed of current vacancies.
- **Sales and investment analysts** using hiring activity as a company signal.
- **Data engineers** loading public job records into a warehouse, spreadsheet, CRM, or BI tool.
- **Job seekers and career products** monitoring new remote or company-specific opportunities.

Use a source-specific ATS Actor when you need another platform. Gupy Scraper only returns jobs published on Gupy's public portal.

### Why use this Actor?

Gupy job pages are designed for people, not recurring data workflows. This Actor provides:

- typed, documented output instead of page markup;
- cleaned plain-text descriptions by default;
- stable IDs for deduplication and change detection;
- bounded offset pagination beyond the first results page;
- transient retry handling for timeouts, rate limits, and temporary server errors;
- no login, browser, cookie, or user-supplied proxy configuration;
- pay-per-result billing, so rejected or duplicate rows are not item-charged.

### What Gupy data can I extract?

| Field | Meaning |
| --- | --- |
| `jobId` | Stable public Gupy job identifier |
| `companyId` | Gupy company identifier when supplied |
| `title` | Published vacancy title |
| `companyName` | Public employer career-page name |
| `description` | Cleaned job description, requirements, and benefits |
| `descriptionHtml` | Optional original description HTML |
| `city`, `state`, `country` | Published location components |
| `location` | Combined human-readable location |
| `workplaceType` | `remote`, `hybrid`, or `on-site` |
| `employmentType` | Gupy vacancy type code |
| `isRemote` | Normalized remote-work flag |
| `isDisabilityInclusive` | Public disability-inclusion marker |
| `skills` | Skills attached to the listing |
| `publishedAt` | Publication timestamp |
| `applicationDeadline` | Application deadline when supplied |
| `applicationUrl` | Canonical public application page |
| `companyCareerUrl` | Employer career page when supplied |
| `scrapedAt` | UTC extraction timestamp |

Optional upstream fields can be absent. Required identifiers, title, description, location string, application URL, source, and extraction timestamp are always emitted for accepted rows.

### How to scrape Gupy jobs

1. Open the Actor in Apify Console.
2. Enter a `keyword`, `company`, or `workplaceType` filter. You can combine them.
3. Choose newest-first or relevance sorting.
4. Set `maxItems` to the most records you need.
5. Enable raw HTML only if your workflow requires it.
6. Click **Start**.
7. Open the default dataset to preview, download, or integrate the records.

A useful first run is:

```json
{
  "keyword": "software engineer",
  "sortBy": "relevance",
  "maxItems": 10,
  "includeHtmlDescription": false
}
```

### Input parameters

| Parameter | Type | Default | Description |
| --- | --- | --- | --- |
| `keyword` | string | empty | Job title or search phrase, maximum 200 characters |
| `company` | string | empty | Exact public Gupy career-page name, such as `Embraer` |
| `workplaceType` | string | empty | `remote`, `hybrid`, or `on-site` |
| `sortBy` | string | `publishedDate` | Newest-first or relevance ordering |
| `maxItems` | integer | `100` | Output limit from 1 to 10,000 |
| `includeHtmlDescription` | boolean | `false` | Include `descriptionHtml` alongside cleaned text |

An empty filter set returns the newest public jobs across Gupy. Filters are sent to the public source, rather than being applied only after downloading unrelated records.

### Output example

This shortened record comes from a real local run with the `software engineer` example input:

```json
{
  "jobId": 3989785,
  "companyId": 1953,
  "title": "Integration Software Engineer",
  "companyName": "Ewave do Brasil",
  "description": "A oportunidade envolve integração de software...",
  "city": "Curitiba",
  "state": "Paraná",
  "country": "Brasil",
  "location": "Curitiba, Paraná, Brasil",
  "workplaceType": "on-site",
  "isRemote": false,
  "skills": [],
  "applicationUrl": "https://vagasewave.gupy.io/job/eyJqb2JJZCI6Mzk4OTc4NSwic291cmNlIjoiZ3VweV9wb3J0YWwifQ==?jobBoardSource=gupy_portal",
  "source": "gupy",
  "scrapedAt": "2026-07-29T02:43:00.000Z"
}
```

Results are stored in the run's default dataset. Use the **Gupy jobs** view for a compact table or download the full records as JSON, CSV, Excel, XML, or RSS.

### How much does it cost to extract Gupy jobs?

This Actor uses pay-per-event pricing: one small start event per run plus one `item` event for each accepted dataset record. The item price decreases across Apify usage tiers.

At the BRONZE rate of **$0.001336 per job** plus the **$0.001 run start**, approximate examples are:

- 10 jobs: approximately 1.436 cents
- 100 jobs: approximately 13.46 cents
- 1,000 jobs: approximately 133.7 cents

Your active Apify tier determines the exact item rate shown before starting a run. Failed, duplicate, incomplete, or empty result rows do not create an item charge.

### Monitoring and integration workflows

#### Monitor remote hiring

Run daily with `workplaceType: "remote"`, `sortBy: "publishedDate"`, and compare `jobId` against the previous dataset. Send unseen IDs to Slack, email, or a recruitment dashboard.

#### Track one employer

Use an exact `company` value such as `Embraer`. Store `publishedAt`, `applicationDeadline`, and `employmentType` to analyze hiring cadence and role mix.

#### Build a data pipeline

Schedule the Actor, connect the dataset webhook to Make or Zapier, and load rows into Google Sheets, Airtable, BigQuery, Snowflake, or your own API. Use `jobId` as the source key and `scrapedAt` as ingestion metadata.

#### Create labor-market aggregates

Collect keyword groups in separate runs. Aggregate `state`, `city`, `workplaceType`, `companyName`, and publication dates without attempting to infer protected or unpublished applicant information.

### Use Gupy Scraper with the Apify API

Replace `YOUR_TOKEN` with an Apify API token.

#### cURL

```bash
curl -X POST \
  "https://api.apify.com/v2/acts/automation-lab~gupy-jobs-scraper/run-sync-get-dataset-items?token=YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"workplaceType":"remote","sortBy":"publishedDate","maxItems":25}'
```

#### JavaScript

```javascript
import { ApifyClient } from 'apify-client';

const client = new ApifyClient({ token: process.env.APIFY_TOKEN });
const run = await client.actor('automation-lab/gupy-jobs-scraper').call({
  company: 'Embraer',
  maxItems: 100,
  sortBy: 'publishedDate',
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python

```python
from apify_client import ApifyClient

client = ApifyClient(token="YOUR_TOKEN")
run = client.actor("automation-lab/gupy-jobs-scraper").call(run_input={
    "keyword": "data analyst",
    "maxItems": 100,
    "sortBy": "relevance",
})
items = client.dataset(run["defaultDatasetId"]).list_items().items
print(items)
```

For asynchronous systems, start a normal run and poll its status or attach a webhook instead of using the synchronous endpoint.

### Use Gupy Scraper through MCP

Add the Apify MCP server to Claude Code:

```bash
claude mcp add --transport http apify \
  "https://mcp.apify.com?tools=automation-lab/gupy-jobs-scraper"
```

#### Claude Desktop, Cursor, and VS Code setup

Desktop and editor clients can use this MCP JSON configuration:

```json
{
  "mcpServers": {
    "apify": {
      "url": "https://mcp.apify.com?tools=automation-lab/gupy-jobs-scraper"
    }
  }
}
```

Example prompts:

- "Run Gupy Scraper for the 25 newest remote jobs and summarize the employers hiring most often."
- "Extract current Embraer Gupy jobs and return deadlines with application links."
- "Find Gupy software engineer listings, then group them by workplace model."

### Tips for reliable runs

- Start with 10–100 items while validating a new keyword or company name.
- Use the exact public career-page company name; broad or misspelled names may return no results.
- Keep newest-first sorting for scheduled monitoring so recent changes appear first.
- Leave raw HTML disabled unless formatting markup is genuinely needed.
- Deduplicate recurring exports by `jobId`, not title, because employers can reuse titles.
- Treat `applicationDeadline` and other optional source fields as nullable in downstream systems.

### Limits and failure behavior

- The Actor collects only public Gupy listings available when the run executes.
- Closed, private, candidate-only, or removed vacancies are not recoverable.
- Gupy controls source fields and may omit a location, deadline, company URL, or skill list.
- A successful no-result search returns an empty dataset and a zero matching count in logs.
- Malformed input fails before source requests are made.
- Temporary network errors, rate limits, and server errors are retried with bounded backoff.
- Stable 4xx responses and unexpected response shapes fail instead of being misreported as empty data.
- The Actor has no automatic browser or residential-proxy fallback, so there is no hidden proxy transfer charge.

### Responsible and legal use

This Actor accesses public job advertisements. Public availability does not remove your obligations.

- Follow Gupy's terms, applicable website rules, and local law.
- Collect only data necessary for a legitimate purpose.
- Do not use results to discriminate against applicants or infer sensitive traits.
- Respect deletion, correction, retention, and attribution obligations that apply to your use case.
- Do not combine public job data with unlawfully obtained personal information.

You are responsible for deciding whether your collection and downstream processing are lawful. This documentation is not legal advice.

### Troubleshooting

#### My company search returns no jobs

Check the exact employer name displayed on its Gupy career page. Try a keyword-only run to discover the value in `companyName`, then reuse that exact string.

#### I received fewer rows than `maxItems`

`maxItems` is a ceiling, not a promise. The source may have fewer matching public records. Inspect the run log's `matchingJobs` and active filters.

#### A run fails with a Gupy API error

Review the HTTP status in the log. Retry later for a persistent 429 or 5xx. Stable 4xx errors usually indicate that the upstream interface changed; include the run URL when reporting the problem.

#### Why is a description plain text?

Plain text is the default for easier exports. Set `includeHtmlDescription` to `true` when you also need the original markup.

### Related Automation Lab Actors

- [Comeet Jobs Scraper](https://apify.com/automation-lab/comeet-jobs-scraper) for public Comeet career pages.
- [Jobvite Careers Jobs Scraper](https://apify.com/automation-lab/jobvite-careers-jobs-scraper) for Jobvite-hosted employer listings.
- [Teamtailor Jobs Scraper](https://apify.com/automation-lab/teamtailor-jobs-scraper) for Teamtailor career sites.

These are separate sources. They are not required to use Gupy Scraper.

### FAQ

#### Does the Actor require a Gupy account?

No. It extracts public job advertisements and does not access candidate profiles or applications.

#### Can it monitor new jobs automatically?

Yes. Schedule newest-first runs in Apify and compare stable `jobId` values in your destination. The Actor emits snapshots; it does not maintain a hidden cross-run history.

#### Does it scrape Gupy Azul, Gupy Embraer, or other company pages?

It searches public jobs exposed through Gupy. For Embraer, use `company: "Embraer"`. A brand term only works when the current public source has matching listings; the Actor does not log in to company or candidate accounts.

#### Can I export to Excel or Google Sheets?

Yes. Download the default dataset as Excel/CSV or connect the run to Google Sheets through an Apify integration, Make, Zapier, or a webhook.

#### Are the results real time?

They reflect the public source at request time. "Real time" is not guaranteed because Gupy controls publication and cache timing.

#### Will the Actor apply for jobs?

No. It only searches and extracts public listing data. Applications remain on the canonical `applicationUrl` and may require a candidate account.

# Actor input Schema

## `keyword` (type: `string`):

Job title or search term, for example software engineer, data analyst, or estágio.

## `company` (type: `string`):

Exact Gupy career-page name, for example Embraer. Leave empty to search all companies.

## `workplaceType` (type: `string`):

Return remote, hybrid, or on-site jobs only. Leave empty for every workplace model.

## `sortBy` (type: `string`):

Use publication date for monitoring recent jobs or relevance for keyword research.

## `maxItems` (type: `integer`):

Maximum number of matching job records to save.

## `includeHtmlDescription` (type: `boolean`):

Also return descriptionHtml in addition to the cleaned plain-text description.

## Actor input object example

```json
{
  "keyword": "software engineer",
  "sortBy": "publishedDate",
  "maxItems": 20,
  "includeHtmlDescription": false
}
```

# Actor output Schema

## `overview` (type: `string`):

Open the default dataset using the compact Gupy jobs overview view.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "keyword": "software engineer",
    "sortBy": "publishedDate",
    "maxItems": 20
};

// Run the Actor and wait for it to finish
const run = await client.actor("automation-lab/gupy-jobs-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "keyword": "software engineer",
    "sortBy": "publishedDate",
    "maxItems": 20,
}

# Run the Actor and wait for it to finish
run = client.actor("automation-lab/gupy-jobs-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"])
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "keyword": "software engineer",
  "sortBy": "publishedDate",
  "maxItems": 20
}' |
apify call automation-lab/gupy-jobs-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=automation-lab/gupy-jobs-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/JUDhXlKROubAFEBIx/builds/805daPFGjhcZULiaN/openapi.json