{
  "openapi": "3.0.1",
  "info": {
    "title": "Totaljobs Scraper - UK Job Board",
    "description": "Scrape job listings from Totaljobs.com by keyword and location. Get titles, employers, salaries, full descriptions, company details, and incremental change tracking. Export as JSON, CSV, or Excel.",
    "version": "1.0",
    "x-build-id": "kG4Z6a4qXk17o4RSr"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/parsebird~totaljobs-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-parsebird-totaljobs-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    },
    "/acts/parsebird~totaljobs-scraper/runs": {
      "post": {
        "operationId": "runs-sync-parsebird-totaljobs-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor and returns information about the initiated run in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/runsResponseSchema"
                }
              }
            }
          }
        }
      }
    },
    "/acts/parsebird~totaljobs-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-parsebird-totaljobs-scraper",
        "x-openai-isConsequential": false,
        "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.",
        "tags": [
          "Run Actor"
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/inputSchema"
              }
            }
          }
        },
        "parameters": [
          {
            "name": "token",
            "in": "query",
            "required": true,
            "schema": {
              "type": "string"
            },
            "description": "Enter your Apify token here"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "inputSchema": {
        "type": "object",
        "properties": {
          "startUrls": {
            "title": "🔗 Start URLs",
            "type": "array",
            "description": "Direct Totaljobs search URLs (e.g. `https://www.totaljobs.com/jobs/software-developer/in-london`) or job-detail URLs (`https://www.totaljobs.com/job/.../...job123456789`). When provided, Search term and Location are ignored.",
            "items": {
              "type": "string"
            }
          },
          "query": {
            "title": "🔍 Search term(s)",
            "type": "string",
            "description": "Job search keyword, e.g. `data engineer` or `software-developer`. Use a JSON array `[\"query1\", \"query2\"]` to run several searches. Not required when Start URLs is provided."
          },
          "location": {
            "title": "📍 Location",
            "type": "string",
            "description": "City or region, e.g. `London`, `Manchester`, `Birmingham`. Use a JSON array for multiple locations."
          },
          "geo": {
            "title": "Portal",
            "type": "string",
            "description": "Fixed to Totaljobs (UK). Informational only.",
            "default": "TOTALJOBS"
          },
          "sort": {
            "title": "🔀 Sort by",
            "enum": [
              "relevance",
              "date",
              "salary_low",
              "salary_high"
            ],
            "type": "string",
            "description": "Order results are returned in.",
            "default": "relevance"
          },
          "age": {
            "title": "Posted within (days)",
            "minimum": 1,
            "type": "integer",
            "description": "Only keep jobs posted within this many days (applied to each job's posting date)."
          },
          "remote": {
            "title": "🏠 Remote only",
            "type": "boolean",
            "description": "Only show remote / work-from-home positions.",
            "default": false
          },
          "radius": {
            "title": "📡 Radius (miles)",
            "enum": [
              "",
              "5",
              "10",
              "20",
              "30",
              "40",
              "50",
              "75",
              "100"
            ],
            "type": "string",
            "description": "Search radius around the location, in MILES — this is a UK board and it searches in miles, not kilometres. Only 5, 10, 20 and 30 are answered; any other choice is reduced to 30 miles (about 48 km) and noted in the log. Requires a location."
          },
          "minSalary": {
            "title": "Minimum salary (GBP/year)",
            "minimum": 0,
            "type": "integer",
            "description": "Minimum annual salary filter, in pounds."
          },
          "contractType": {
            "title": "📝 Contract type",
            "enum": [
              "",
              "FULL_TIME",
              "PART_TIME",
              "CONTRACT",
              "TEMPORARY",
              "INTERNSHIP",
              "APPRENTICESHIP",
              "FREELANCE",
              "MINI_JOB",
              "WORKING_STUDENT",
              "VOLUNTEER",
              "THESIS",
              "DUAL_STUDY"
            ],
            "type": "string",
            "description": "Filter by contract / employment type."
          },
          "experience": {
            "title": "Experience level",
            "enum": [
              "",
              "no",
              "required",
              "executive"
            ],
            "type": "string",
            "description": "Filter by experience level (best-effort, applied to the parsed job)."
          },
          "workType": {
            "title": "Work type",
            "enum": [
              "",
              "FULL_TIME",
              "PART_TIME"
            ],
            "type": "string",
            "description": "Filter by work schedule (full-time / part-time)."
          },
          "companyId": {
            "title": "Company ID",
            "minimum": 1,
            "type": "integer",
            "description": "Filter to a single employer by its numeric Totaljobs company ID (see the `companyId` output field)."
          },
          "language": {
            "title": "🌐 Language",
            "type": "string",
            "description": "Filter by job-posting language, e.g. `en` or `de`."
          },
          "applicationMethod": {
            "title": "Application method",
            "enum": [
              "",
              "INTERNAL",
              "EXTERNAL"
            ],
            "type": "string",
            "description": "Filter by how to apply. `INTERNAL` = apply on Totaljobs, `EXTERNAL` = apply on the employer's site."
          },
          "excludeSponsored": {
            "title": "Exclude sponsored",
            "type": "boolean",
            "description": "Skip sponsored / promoted listings (`isSponsored = true`).",
            "default": false
          },
          "includeKeywords": {
            "title": "📝 Include keywords",
            "type": "object",
            "description": "Require at least one of these keywords in the title / description / skills. Example: {\"keywords\":[\"React\",\"Node.js\"],\"matchTitle\":true,\"matchDescription\":true,\"matchSkills\":true}."
          },
          "excludeKeywords": {
            "title": "🚫 Exclude keywords",
            "type": "object",
            "description": "Exclude jobs containing any of these keywords. Same config shape as Include keywords."
          },
          "fromDate": {
            "title": "📅 From date",
            "type": "string",
            "description": "Only include jobs posted on or after this date. Accepts `YYYY-MM-DD` or ISO-8601."
          },
          "toDate": {
            "title": "📅 To date",
            "type": "string",
            "description": "Only include jobs posted on or before this date."
          },
          "maxAgeMinutes": {
            "title": "⏰ Max age (minutes)",
            "minimum": 0,
            "type": "integer",
            "description": "Only include jobs posted within the last N minutes. 0 = no limit. Pairs well with hourly scheduled runs (e.g. 60).",
            "default": 0
          },
          "customFilters": {
            "title": "🔧 Custom filters (advanced)",
            "type": "array",
            "description": "Rules applied to any output field. Each rule: {\"field\":\"\",\"op\":\"includes|notIncludes|equals|notEquals|gt|gte|lt|lte\",\"value\":...}. Example: [{\"field\":\"location\",\"op\":\"includes\",\"value\":\"London\"}, {\"field\":\"unifiedSalary.min\",\"op\":\"gte\",\"value\":50000}]."
          },
          "includeDetails": {
            "title": "📋 Include full details",
            "type": "boolean",
            "description": "Fetch each job's detail page for the full description, ISO dates, employment type, industry, and geo-coordinates. Slower but much richer data.",
            "default": true
          },
          "detailEngine": {
            "title": "Detail page mode",
            "enum": [
              "auto",
              "cheerio",
              "playwright"
            ],
            "type": "string",
            "description": "Controls how job detail pages are fetched. Auto (recommended) lets the actor choose the best method automatically. Lightweight is faster; Enhanced is heavier but more reliable.",
            "default": "auto"
          },
          "descriptionFormat": {
            "title": "Description format",
            "enum": [
              "html",
              "text",
              "markdown",
              "original"
            ],
            "type": "string",
            "description": "Format for the job description text (requires Include full details).",
            "default": "html"
          },
          "maxResults": {
            "title": "💯 Max results",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Maximum number of job listings to return. This is the number of billed rows. 0 = unlimited.",
            "default": 100
          },
          "maxPages": {
            "title": "📄 Max pages",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Maximum search-result pages to scrape (25 jobs/page). Automatically raised when Max results requires more pages, so this is rarely a hard cap.",
            "default": 10
          },
          "compact": {
            "title": "📦 Compact output",
            "type": "boolean",
            "description": "Return only the 11 most essential fields (jobKey, title, company, location, url, portalUrl, datePosted, workFromHome, unifiedSalary, geo, description) — for AI-agent and MCP workflows where token budget matters.",
            "default": false
          },
          "descriptionMaxLength": {
            "title": "✂️ Description max length",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Truncate the description field to this many characters, appending '...' if truncated. 0 = no truncation.",
            "default": 0
          },
          "excludeEmptyFields": {
            "title": "Exclude empty fields",
            "type": "boolean",
            "description": "Drop null, empty-string, and empty-array fields from each record. Smaller payloads for AI agents and dashboards.",
            "default": false
          },
          "outputFields": {
            "title": "Output fields",
            "type": "array",
            "description": "Return only this subset of fields. Supports dot notation, e.g. `locationDetail.city` or `unifiedSalary.min`. Empty = all fields.",
            "items": {
              "type": "string"
            }
          },
          "datasetName": {
            "title": "Dataset name",
            "type": "string",
            "description": "Custom named dataset. Supports masks: {DATE} = YYYYMMDD, {TIME} = HHMMSS."
          },
          "mode": {
            "title": "⚙️ Mode",
            "enum": [
              "full",
              "incremental"
            ],
            "type": "string",
            "description": "`full` returns all jobs found. `incremental` returns only jobs not seen (or changed) since previous runs with the same state store. State is scoped per query + location combination.",
            "default": "full"
          },
          "stateStoreName": {
            "title": "State store name",
            "type": "string",
            "description": "Key-value store name for incremental state. Use the same name across scheduled runs.",
            "default": "totaljobs-state"
          },
          "emitUnchanged": {
            "title": "♻️ Emit unchanged records",
            "type": "boolean",
            "description": "In incremental mode, also emit records that haven't changed since the last run.",
            "default": false
          },
          "emitExpired": {
            "title": "⚰️ Emit expired records",
            "type": "boolean",
            "description": "In incremental mode, also emit records that are no longer found on the site.",
            "default": false
          },
          "skipReposts": {
            "title": "🚫 Skip reposts",
            "type": "boolean",
            "description": "Exclude listings detected as reposts of previously seen jobs.",
            "default": false
          },
          "dedupStoreName": {
            "title": "Dedup store name",
            "type": "string",
            "description": "Named key-value store for cross-run dedup (used when Mode is `full`). Same name across runs = only new jobs are pushed."
          },
          "dedupKey": {
            "title": "Dedup key",
            "type": "string",
            "description": "Field used as the unique key for dedup.",
            "default": "jobKey"
          },
          "proxyConfiguration": {
            "title": "🛡️ Proxy configuration",
            "type": "object",
            "description": "Totaljobs blocks datacenter ranges and throttles by IP, so UK residential routing is preset. Change it only for an account-specific setup.",
            "default": {
              "useApifyProxy": true,
              "apifyProxyGroups": [
                "RESIDENTIAL"
              ],
              "apifyProxyCountry": "GB"
            }
          }
        }
      },
      "runsResponseSchema": {
        "type": "object",
        "properties": {
          "data": {
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "actId": {
                "type": "string"
              },
              "userId": {
                "type": "string"
              },
              "startedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "finishedAt": {
                "type": "string",
                "format": "date-time",
                "example": "2025-01-08T00:00:00.000Z"
              },
              "status": {
                "type": "string",
                "example": "READY"
              },
              "meta": {
                "type": "object",
                "properties": {
                  "origin": {
                    "type": "string",
                    "example": "API"
                  },
                  "userAgent": {
                    "type": "string"
                  }
                }
              },
              "stats": {
                "type": "object",
                "properties": {
                  "inputBodyLen": {
                    "type": "integer",
                    "example": 2000
                  },
                  "rebootCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "restartCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "resurrectCount": {
                    "type": "integer",
                    "example": 0
                  },
                  "computeUnits": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "options": {
                "type": "object",
                "properties": {
                  "build": {
                    "type": "string",
                    "example": "latest"
                  },
                  "timeoutSecs": {
                    "type": "integer",
                    "example": 300
                  },
                  "memoryMbytes": {
                    "type": "integer",
                    "example": 1024
                  },
                  "diskMbytes": {
                    "type": "integer",
                    "example": 2048
                  }
                }
              },
              "buildId": {
                "type": "string"
              },
              "defaultKeyValueStoreId": {
                "type": "string"
              },
              "defaultDatasetId": {
                "type": "string"
              },
              "defaultRequestQueueId": {
                "type": "string"
              },
              "buildNumber": {
                "type": "string",
                "example": "1.0.0"
              },
              "containerUrl": {
                "type": "string"
              },
              "usage": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "integer",
                    "example": 1
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              },
              "usageTotalUsd": {
                "type": "number",
                "example": 0.00005
              },
              "usageUsd": {
                "type": "object",
                "properties": {
                  "ACTOR_COMPUTE_UNITS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATASET_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "KEY_VALUE_STORE_WRITES": {
                    "type": "number",
                    "example": 0.00005
                  },
                  "KEY_VALUE_STORE_LISTS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_READS": {
                    "type": "integer",
                    "example": 0
                  },
                  "REQUEST_QUEUE_WRITES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_INTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "DATA_TRANSFER_EXTERNAL_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_RESIDENTIAL_TRANSFER_GBYTES": {
                    "type": "integer",
                    "example": 0
                  },
                  "PROXY_SERPS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}