{
  "openapi": "3.0.1",
  "info": {
    "title": "Superprof Tutor Scraper [💰$0.81] — Prices, Ratings and Lessons",
    "description": "Search Superprof tutors by subject and city on 18 country sites. Every row gives the tutor name, hourly price, rating and profile link in one clean table. Schedule repeat runs to spot tutors that have joined since last time.",
    "version": "0.1",
    "x-build-id": "C5Bpu81CF1MdGKfng"
  },
  "servers": [
    {
      "url": "https://api.apify.com/v2"
    }
  ],
  "paths": {
    "/acts/blackfalcondata~superprof-co-uk-scraper/run-sync-get-dataset-items": {
      "post": {
        "operationId": "run-sync-get-dataset-items-blackfalcondata-superprof-co-uk-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~superprof-co-uk-scraper/runs": {
      "post": {
        "operationId": "runs-sync-blackfalcondata-superprof-co-uk-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~superprof-co-uk-scraper/run-sync": {
      "post": {
        "operationId": "run-sync-blackfalcondata-superprof-co-uk-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": {
          "query": {
            "title": "🔍 Subject(s)",
            "type": "string",
            "description": "Subject to search, e.g. \"maths\", \"english\", \"guitar\", \"yoga\". Use a JSON array for several subjects in one run (e.g. [\"maths\",\"physics\"]). Leave the subject empty and give a city to list every tutor near that city. Required if no start URL, city or coordinates are provided."
          },
          "location": {
            "title": "📍 City / Address",
            "type": "string",
            "description": "City or address Superprof geocodes the search around, e.g. \"London\". Use a JSON array for several locations in one run. Leave the subject empty and give a city (or coordinates) to list every tutor there. Give a subject without a city to search the whole country site. A run needs at least a subject, a city, coordinates or a start URL."
          },
          "country": {
            "title": "🌍 Superprof Country Site",
            "enum": [
              "uk",
              "ie",
              "com",
              "in",
              "fr",
              "es",
              "de",
              "it",
              "be",
              "ch",
              "ca",
              "au",
              "br",
              "mx",
              "pt",
              "lu",
              "at",
              "nz"
            ],
            "type": "string",
            "description": "Which Superprof country site to search (18 country sites). Prices and currency follow the site.",
            "default": "uk"
          },
          "maxResults": {
            "title": "💯 Max Results",
            "minimum": 0,
            "maximum": 1000,
            "type": "integer",
            "description": "Maximum total tutors (0 = unlimited).",
            "default": 100
          },
          "maxPages": {
            "title": "📄 Max Pages",
            "minimum": 1,
            "maximum": 100,
            "type": "integer",
            "description": "Maximum result pages to read per search (18 tutors per page). If both maxResults and maxPages are set, the lower cap wins.",
            "default": 30
          },
          "startUrls": {
            "title": "🔗 Start URLs",
            "type": "array",
            "description": "Paste raw Superprof search URLs. Each URL becomes its own search task; results are merged and deduped by tutor ID across all URLs. When provided, startUrls REPLACE the subject/city fields (unsupported URLs are skipped, and if none is supported the run stops with an input error).",
            "items": {
              "type": "string"
            },
            "default": []
          },
          "compact": {
            "title": "📦 Compact Output",
            "type": "boolean",
            "description": "Core fields only (for AI-agent/MCP workflows).",
            "default": false
          },
          "excludeEmptyFields": {
            "title": "Exclude empty fields from output",
            "type": "boolean",
            "description": "Drop null, empty-string, and empty-array fields from each record before push. Smaller payloads for AI agents and dashboards.",
            "default": false
          },
          "incrementalMode": {
            "title": "♻️ Incremental Mode",
            "type": "boolean",
            "description": "Compare against previous run state. stateKey is optional — defaults to a value derived from search inputs (subjects, cities, startUrls, country site) so different filter sets never share state.",
            "default": false
          },
          "stateKey": {
            "title": "🔑 State Key",
            "type": "string",
            "description": "Optional. Stable identifier for the tracked search universe. Leave empty to auto-generate from search inputs."
          },
          "emitUnchanged": {
            "title": "♻️ Emit Unchanged Records",
            "type": "boolean",
            "description": "When incremental, also emit records that haven't changed.",
            "default": false
          },
          "emitExpired": {
            "title": "⚰️ Emit Expired Records",
            "type": "boolean",
            "description": "When incremental, also emit records no longer found.",
            "default": false
          },
          "skipReposts": {
            "title": "🚫 Skip Reposts",
            "type": "boolean",
            "description": "When incremental, skip tutors whose content matches a listing that expired in a prior run (cross-run duplicate detection).",
            "default": false
          },
          "notifyOnlyChanges": {
            "title": "🔄 Notify Only New/Updated",
            "type": "boolean",
            "description": "When Incremental Mode is on, only send notifications for NEW and UPDATED tutors. Has no effect outside incremental mode.",
            "default": false
          },
          "notificationLimit": {
            "title": "📊 Max Listings Per Notification",
            "minimum": 1,
            "maximum": 20,
            "type": "integer",
            "description": "Maximum number of tutors included in each notification message (1–20).",
            "default": 5
          },
          "telegramToken": {
            "title": "🔑 Telegram Bot Token",
            "type": "string",
            "description": "Telegram bot token (from @BotFather). Required for Telegram notifications."
          },
          "telegramChatId": {
            "title": "💬 Telegram Chat ID",
            "type": "string",
            "description": "Telegram chat or channel ID (e.g. \"-100123456789\"). Required when telegramToken is set."
          },
          "discordWebhookUrl": {
            "title": "🎮 Discord Webhook URL",
            "type": "string",
            "description": "Discord incoming webhook URL. Server Settings → Integrations → Webhooks → New Webhook."
          },
          "slackWebhookUrl": {
            "title": "💼 Slack Webhook URL",
            "type": "string",
            "description": "Slack incoming webhook URL. api.slack.com/messaging/webhooks."
          },
          "whatsappPhoneNumberId": {
            "title": "📞 WhatsApp Phone Number ID",
            "type": "string",
            "description": "Your WhatsApp Business phone-number ID (numeric, from Meta dashboard). Required when whatsappAccessToken is set."
          },
          "whatsappAccessToken": {
            "title": "📱 WhatsApp Access Token",
            "type": "string",
            "description": "WhatsApp Cloud API permanent access token (System User token from Meta Business). Recipient must have messaged the business number within the last 24h (service-conversation window — free since Nov 2024)."
          },
          "whatsappTo": {
            "title": "📲 WhatsApp Recipient",
            "type": "string",
            "description": "Recipient phone in E.164 format without + (e.g. \"436641234567\"). Recipient must have messaged your business number within last 24h."
          },
          "webhookUrl": {
            "title": "🪝 Generic Webhook URL",
            "type": "string",
            "description": "Receives a JSON POST with {metadata, items} after each run. Universal escape hatch for n8n / Make / Zapier / custom backends."
          },
          "webhookHeaders": {
            "title": "📋 Webhook Headers",
            "type": "object",
            "description": "Optional JSON object of custom headers (e.g. {\"Authorization\":\"Bearer ...\"})."
          },
          "appConnector": {
            "title": "Send results to a connected app",
            "type": "string",
            "description": "Optional. Pick a connected app under Settings → API & Integrations to receive your results (including any contact details). Best-effort across MCP connectors as Apify expands its catalog."
          },
          "mcpIssueTeam": {
            "title": "Issue tracker team",
            "type": "string",
            "description": "Only when the connected app is an issue tracker: the team (name or ID) the summary issue is created under, if that app requires one."
          },
          "descriptionFormat": {
            "title": "📝 Description Format",
            "enum": [
              "all",
              "text",
              "html",
              "markdown"
            ],
            "type": "string",
            "description": "Choose which representation of the listing description to include. `all` keeps every variant; the others keep only the selected one.",
            "default": "all"
          },
          "radiusKm": {
            "title": "📏 Max Distance (km)",
            "minimum": 0,
            "maximum": 500,
            "type": "integer",
            "description": "Only keep tutors whose listed distance from the searched place is at most this many kilometres. 0 = no limit.",
            "default": 0
          },
          "minPrice": {
            "title": "💷 Minimum hourly price",
            "minimum": 0,
            "type": "integer",
            "description": "Lowest hourly price to keep, in the site's own currency. Sent to Superprof's own price filter and re-checked on every result. Empty = no minimum."
          },
          "maxPrice": {
            "title": "💷 Maximum hourly price",
            "minimum": 0,
            "type": "integer",
            "description": "Highest hourly price to keep, in the site's own currency. Sent to Superprof's own price filter and re-checked on every result. Empty = no maximum."
          },
          "webcamOnly": {
            "title": "💻 Online lessons only",
            "type": "boolean",
            "description": "Search Superprof's online (webcam) lessons instead of lessons near a place, and keep only tutors who teach by webcam.",
            "default": false
          },
          "orderBy": {
            "title": "↕️ Sort results by",
            "enum": [
              "pertinence_DESC",
              "distance_ASC",
              "price_ASC",
              "price_DESC",
              "rating_DESC"
            ],
            "type": "string",
            "description": "Relevance and distance are applied by Superprof. Price and rating orders are applied by this actor over the tutors it reads for each search: every page up to Max pages is read first, sorted, then delivered.",
            "default": "pertinence_DESC"
          },
          "latitude": {
            "title": "🌐 Latitude",
            "type": "string",
            "description": "Search around these coordinates instead of a city (give both latitude and longitude), e.g. \"55.9533\". When set, the coordinates decide the place, not the city field."
          },
          "longitude": {
            "title": "🌐 Longitude",
            "type": "string",
            "description": "Longitude for a coordinate search, e.g. \"-3.1883\". Used only together with latitude."
          },
          "distance": {
            "title": "🎯 Distance around the coordinates (km)",
            "minimum": 1,
            "maximum": 1000,
            "type": "integer",
            "description": "How far around the coordinates Superprof searches, in kilometres. Used only with latitude and longitude.",
            "default": 200
          }
        }
      },
      "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "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
                  },
                  "PROXY_UNBLOCKER_UNITS": {
                    "type": "integer",
                    "example": 0
                  }
                }
              }
            }
          }
        }
      }
    }
  }
}