{
  "openapi": "3.0.1",
  "info": {
    "title": "Totaljobs Scraper - UK’s Largest Job Board",
    "description": "Scrape totaljobs.com - UK’s largest job board. Salary data, employer contact details, full job descriptions, and job change monitoring. Incremental mode detects new and changed listings. Compact output for AI agents and MCP workflows.",
    "version": "1.0",
    "x-build-id": "YSvspzZMjZmUUOLiH"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blackfalcondata~totaljobs-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blackfalcondata-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/blackfalcondata~totaljobs-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blackfalcondata-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/blackfalcondata~totaljobs-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blackfalcondata-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 to scrape. If provided, query and location are ignored.",
            "items": {
              "type": "object",
              "required": [
                "url"
              ],
              "properties": {
                "url": {
                  "type": "string",
                  "title": "URL of a web page",
                  "format": "uri"
                }
              }
            }
          },
          "query": {
            "title": "Search Query",
            "type": "string",
            "description": "Job search keyword (e.g., 'software-developer', 'data-analyst'). Not required when startUrls is provided."
          },
          "location": {
            "title": "Location",
            "type": "string",
            "description": "Location filter (e.g., 'London', 'Manchester', 'Birmingham')"
          },
          "geo": {
            "title": "Portal",
            "type": "string",
            "description": "Fixed to Totaljobs (UK).",
            "default": "TOTALJOBS"
          },
          "sort": {
            "title": "Sort By",
            "enum": [
              "relevance",
              "date",
              "salary_low",
              "salary_high"
            ],
            "type": "string",
            "description": "Sort order for results",
            "default": "relevance"
          },
          "age": {
            "title": "Posted Within",
            "minimum": 1,
            "type": "integer",
            "description": "Only show jobs posted within this many days"
          },
          "remote": {
            "title": "Remote Only",
            "type": "boolean",
            "description": "Only show remote/home office positions"
          },
          "radius": {
            "title": "Radius (km)",
            "enum": [
              "5",
              "10",
              "20",
              "30",
              "40",
              "50",
              "75",
              "100"
            ],
            "type": "string",
            "description": "Search radius around location in km (requires location)"
          },
          "minSalary": {
            "title": "Minimum Salary",
            "minimum": 0,
            "type": "integer",
            "description": "Minimum annual salary filter (GBP)"
          },
          "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"
          },
          "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 by StepStone company ID (numeric)"
          },
          "language": {
            "title": "Language",
            "type": "string",
            "description": "Filter by job posting language (e.g., 'en', 'de')"
          },
          "applicationMethod": {
            "title": "Application Method",
            "enum": [
              "INTERNAL",
              "EXTERNAL"
            ],
            "type": "string",
            "description": "Filter by how to apply (e.g., INTERNAL = apply on company site only)"
          },
          "excludeSponsored": {
            "title": "Exclude Sponsored",
            "type": "boolean",
            "description": "Skip sponsored/promoted listings. Filters out items where isSponsored=true.",
            "default": false
          },
          "includeDetails": {
            "title": "Include Detail Pages",
            "type": "boolean",
            "description": "Fetch each job's detail page for full description, ISO dates, salary, 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 but may fail on protected portals. Enhanced is heavier but more reliable.",
            "default": "auto"
          },
          "descriptionFormat": {
            "title": "Description Format",
            "enum": [
              "html",
              "text",
              "markdown",
              "original"
            ],
            "type": "string",
            "description": "Format for job description text (requires Include Detail Pages)",
            "default": "html"
          },
          "maxResults": {
            "title": "Max Results",
            "minimum": 0,
            "type": "integer",
            "description": "Maximum number of job listings to return (0 = unlimited)",
            "default": 100
          },
          "maxPages": {
            "title": "Max Pages",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Maximum number of search result pages to scrape",
            "default": 10
          },
          "mode": {
            "title": "Mode",
            "enum": [
              "full",
              "incremental"
            ],
            "type": "string",
            "description": "full = return all jobs found. incremental = only return jobs not seen in previous runs (requires stateStoreName).",
            "default": "full"
          },
          "stateStoreName": {
            "title": "State Store Name",
            "type": "string",
            "description": "KV store name for incremental state. Use same name across scheduled runs. State is scoped per query+location+geo combination.",
            "default": "totaljobs-state"
          },
          "dedupStoreName": {
            "title": "Dedup Store Name",
            "type": "string",
            "description": "Named KV store for cross-run dedup. Same name across runs = only new jobs pushed."
          },
          "dedupKey": {
            "title": "Dedup Key",
            "type": "string",
            "description": "Field used as unique key for dedup (default: jobKey)",
            "default": "jobKey"
          },
          "datasetName": {
            "title": "Dataset Name",
            "type": "string",
            "description": "Custom dataset name. Supports masks: {DATE} = YYYYMMDD, {TIME} = HHMMSS"
          },
          "outputFields": {
            "title": "Output Fields",
            "type": "array",
            "description": "Select subset of output fields. Use dot notation for nested: 'ceSalary.min'. If empty: all fields returned."
          },
          "compact": {
            "title": "Compact Mode",
            "type": "boolean",
            "description": "When true, each result contains only the 11 most essential fields: jobKey, title, company, location, url, portalUrl, datePosted, workFromHome, unifiedSalary, geo, and description. Use this in AI-agent and MCP workflows where token budgets matter.",
            "default": false
          },
          "descriptionMaxLength": {
            "title": "Description Max Length (chars)",
            "minimum": 0,
            "maximum": 10000,
            "type": "integer",
            "description": "Truncate the description field to this many characters, appending '...' if truncated. 0 means no truncation. Use in AI-agent workflows to control context window usage. Pairs well with compact mode.",
            "default": 0
          },
          "proxyConfiguration": {
            "title": "Proxy Configuration",
            "type": "object",
            "description": "Proxy configuration. Some portals require enhanced proxy (handled automatically). Your Apify plan must include proxy access.",
            "default": {
              "useApifyProxy": true
            }
          },
          "maxConcurrency": {
            "title": "Max Concurrency",
            "minimum": 1,
            "maximum": 50,
            "type": "integer",
            "description": "Maximum number of concurrent requests",
            "default": 5
          },
          "maxRequestRetries": {
            "title": "Max Request Retries",
            "minimum": 0,
            "maximum": 10,
            "type": "integer",
            "description": "Maximum number of retries per request",
            "default": 3
          },
          "_benchDelayMs": {
            "title": "[Internal] Benchmark Delay (ms)",
            "minimum": 0,
            "type": "integer",
            "description": "Override request delay for benchmarking. Internal use only — not for production."
          },
          "_benchFreshSession": {
            "title": "[Internal] Benchmark Fresh Session",
            "type": "boolean",
            "description": "Override fresh session flag for benchmarking. Internal use only — not for production."
          }
        }
      },
      "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
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}