{ "openapi": "3.1.0", "info": { "title": "ProLevelMax API", "version": "1.4.0", "description": "Live public data from social media and the web for AI agents and developers. Find a source with /v1/discover, read its input fields and quote with /v1/inspect, run it with /v1/run. Every run is billed to your prepaid balance and never costs more than its quote.", "contact": { "email": "toph@prolevelmax.com", "url": "https://prolevelmax.com/contact" } }, "servers": [ { "url": "https://prolevelmax.com" } ], "security": [ { "apiKey": [] } ], "paths": { "/v1/schedules": {"get": {"operationId": "listSchedules", "summary": "Your scheduled runs", "responses": {"200": {"description": "Schedules", "content": {"application/json": {"schema": {"type": "object", "properties": {"schedules": {"type": "array", "items": {"$ref": "#/components/schemas/Schedule"}}}}}}}, "401": {"$ref": "#/components/responses/Error"}}}, "post": {"operationId": "createSchedule", "summary": "Run a source every day or every week at a set Beijing time", "description": "Each run is billed like POST /v1/run and never costs more than runCap. Send dryRun: true first to get a preview (cost per run, most per month, first run) without saving; show it to the user and create the schedule only after they agree.", "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ScheduleRequest"}}}}, "responses": {"201": {"description": "Created", "content": {"application/json": {"schema": {"type": "object", "properties": {"schedule": {"$ref": "#/components/schemas/Schedule"}}}}}}, "200": {"description": "Preview (dryRun: true); nothing saved", "content": {"application/json": {"schema": {"type": "object", "properties": {"preview": {"$ref": "#/components/schemas/SchedulePreview"}}}}}}, "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}, "409": {"$ref": "#/components/responses/Error"}, "422": {"$ref": "#/components/responses/Error"}}}}, "/v1/schedules/{id}": {"get": {"operationId": "getSchedule", "summary": "One schedule", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Schedule id (sch_…)"}], "responses": {"200": {"description": "The schedule", "content": {"application/json": {"schema": {"type": "object", "properties": {"schedule": {"$ref": "#/components/schemas/Schedule"}}}}}}, "401": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}}, "patch": {"operationId": "updateSchedule", "summary": "Change a schedule, or turn it on or off", "description": "Send only the fields to change. enabled: true turns a paused schedule back on and clears the pause.", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Schedule id (sch_…)"}], "requestBody": {"required": true, "content": {"application/json": {"schema": {"$ref": "#/components/schemas/ScheduleRequest"}}}}, "responses": {"200": {"description": "The schedule", "content": {"application/json": {"schema": {"type": "object", "properties": {"schedule": {"$ref": "#/components/schemas/Schedule"}}}}}}, "400": {"$ref": "#/components/responses/Error"}, "401": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}, "422": {"$ref": "#/components/responses/Error"}}}, "delete": {"operationId": "deleteSchedule", "summary": "Delete a schedule (past runs are kept)", "parameters": [{"name": "id", "in": "path", "required": true, "schema": {"type": "string"}, "description": "Schedule id (sch_…)"}], "responses": {"200": {"description": "Deleted", "content": {"application/json": {"schema": {"type": "object", "properties": {"ok": {"type": "boolean"}}}}}}, "401": {"$ref": "#/components/responses/Error"}, "404": {"$ref": "#/components/responses/Error"}}}}, "/v1/whoami": { "get": { "operationId": "whoami", "summary": "Verify the API key and return the balance", "responses": { "200": { "description": "Key owner and balance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Whoami" } } } }, "401": { "$ref": "#/components/responses/Error" } } } }, "/v1/discover": { "post": { "operationId": "discover", "summary": "Find data sources for a request (English or Chinese)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "properties": { "query": { "type": "string", "maxLength": 500, "examples": [ "tiktok comments", "小红书 评论" ] }, "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 } } } } } }, "responses": { "200": { "description": "Ranked sources", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DiscoverResult" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" } } } }, "/v1/inspect": { "post": { "operationId": "inspect", "summary": "Input fields, price and quote of one source", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "scraper" ], "properties": { "scraper": { "type": "string", "description": "Source id from discover, e.g. procli_reddit_b" }, "input": { "type": "object", "description": "Optional: the input you plan to send, for a matching quote" }, "maxItems": { "type": "integer", "minimum": 1, "description": "Per-result sources: results you plan to ask for (default 100)" } } } } } }, "responses": { "200": { "description": "Source details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Inspect" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" } } } }, "/v1/run": { "post": { "operationId": "run", "summary": "Run a source (billed to your balance)", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunRequest" } } } }, "responses": { "200": { "description": "Finished run with its results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RunResult" } } } }, "202": { "description": "Async run started", "content": { "application/json": { "schema": { "type": "object", "properties": { "runId": { "type": "string" }, "status": { "const": "pending" }, "pollUrl": { "type": "string" }, "pricing": { "$ref": "#/components/schemas/Pricing" }, "quote": { "$ref": "#/components/schemas/Quote" } } } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "402": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" }, "422": { "$ref": "#/components/responses/Error" }, "429": { "$ref": "#/components/responses/Error" }, "502": { "$ref": "#/components/responses/Error" }, "503": { "$ref": "#/components/responses/Error" } } } }, "/v1/runs": { "get": { "operationId": "listRuns", "summary": "Your recent runs, newest first", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 20 } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0, "default": 0 } } ], "responses": { "200": { "description": "Runs", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/RunSummary" } }, "limit": { "type": "integer" }, "offset": { "type": "integer" } } } } } }, "401": { "$ref": "#/components/responses/Error" } } } }, "/v1/runs/{id}": { "get": { "operationId": "getRun", "summary": "One run: status, cost and results", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "schema": { "type": "integer", "minimum": 0 }, "description": "With limit: read the results in pages" }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 1000 } } ], "responses": { "200": { "description": "Run", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Run" } } } }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" } } } }, "/v1/runs/{id}/download": { "get": { "operationId": "downloadRun", "summary": "Download a run's results as a file", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "format", "in": "query", "schema": { "type": "string", "enum": [ "json", "csv", "xlsx" ], "default": "json" }, "description": "csv is UTF-8 with BOM; nested fields become dotted columns (author.name), lists are joined with '; '" } ], "responses": { "200": { "description": "The file", "content": { "application/json": { "schema": { "type": "array", "items": { "type": "object" } } }, "text/csv": { "schema": { "type": "string" } }, "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet": { "schema": { "type": "string", "format": "binary" } } } }, "400": { "$ref": "#/components/responses/Error" }, "401": { "$ref": "#/components/responses/Error" }, "404": { "$ref": "#/components/responses/Error" }, "409": { "$ref": "#/components/responses/Error" } } } } }, "components": { "securitySchemes": { "apiKey": { "type": "http", "scheme": "bearer", "description": "API key from the dashboard (sk_procli_...)" } }, "responses": { "Error": { "description": "Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } }, "schemas": { "ScheduleRequest": {"type": "object", "required": ["scraper", "input", "frequency", "time"], "properties": {"scraper": {"type": "string", "description": "Source id from discover"}, "input": {"type": "object", "description": "Input fields for this source (see inspect)"}, "maxItems": {"type": ["integer", "null"], "minimum": 1, "description": "Per-result sources: most results per run (default 100)"}, "frequency": {"type": "string", "enum": ["daily", "weekly"]}, "weekday": {"description": "Weekly only: 1 (Monday) to 7 (Sunday), or mon … sun", "oneOf": [{"type": "integer", "minimum": 1, "maximum": 7}, {"type": "string", "enum": ["mon", "tue", "wed", "thu", "fri", "sat", "sun"]}]}, "time": {"type": "string", "pattern": "^\\d{1,2}:\\d{2}$", "description": "HH:MM, 24-hour, Beijing time (UTC+8)"}, "runCap": {"type": ["number", "null"], "description": "Most one run may cost, USD. Default: the source's quote for this input"}, "monthlyCap": {"type": ["number", "null"], "description": "Optional: most this schedule may spend per calendar month (Beijing time), USD"}, "notifyEmail": {"type": "boolean", "default": false, "description": "Email the account owner when each run finishes (results count, cost, link to the run)"}, "enabled": {"type": "boolean", "default": true}, "dryRun": {"type": "boolean", "default": false, "description": "POST only: return a preview and save nothing"}}}, "SchedulePreview": {"type": "object", "properties": {"scraper": {"type": "string"}, "title": {"type": "string"}, "scheduleText": {"type": "string"}, "runCap": {"type": "number"}, "runCapDisplay": {"type": "string"}, "defaultRunCap": {"type": "number"}, "minRunCap": {"type": "number"}, "monthlyCap": {"type": ["number", "null"]}, "mostPerMonthDisplay": {"type": "string"}, "nextRunAt": {"type": "integer", "description": "Epoch ms"}, "nextRunBeijing": {"type": "string", "description": "YYYY-MM-DD HH:MM, Beijing time"}, "summary": {"type": "string", "description": "One sentence to show the user before they confirm"}}}, "Schedule": {"type": "object", "properties": {"id": {"type": "string"}, "scraper": {"type": "string"}, "title": {"type": "string"}, "input": {"type": "object"}, "inputSummary": {"type": "string"}, "maxItems": {"type": ["integer", "null"]}, "frequency": {"type": "string", "enum": ["daily", "weekly"]}, "weekday": {"type": ["integer", "null"]}, "time": {"type": "string"}, "timezone": {"type": "string", "const": "Asia/Shanghai"}, "scheduleText": {"type": "string"}, "runCap": {"type": "number"}, "runCapDisplay": {"type": "string"}, "monthlyCap": {"type": ["number", "null"]}, "monthlyCapDisplay": {"type": ["string", "null"]}, "spentThisMonth": {"type": "number"}, "spentThisMonthDisplay": {"type": "string"}, "enabled": {"type": "boolean"}, "pausedReason": {"type": ["string", "null"], "enum": [null, "off", "failures", "balance", "cap_too_low", "source_gone", "spend_limit"], "description": "Why it is off: turned off by the user, 3 failed runs in a row, balance too low, cap below the source's minimum, the source was removed, or the API key / app that created it reached its spending limit"}, "notifyEmail": {"type": "boolean"}, "running": {"type": "boolean"}, "nextRunAt": {"type": ["integer", "null"], "description": "Epoch ms; null while off"}, "nextRunBeijing": {"type": ["string", "null"]}, "lastRun": {"type": ["object", "null"], "properties": {"id": {"type": "string"}, "status": {"type": "string"}, "at": {"type": "integer"}, "itemsCount": {"type": ["integer", "null"]}, "chargedDisplay": {"type": ["string", "null"]}, "error": {"type": ["string", "null"]}}}, "lastSkip": {"type": "object", "description": "Present when the last due run did not start: monthly_cap, retrying or start_failed", "properties": {"reason": {"type": "string"}, "at": {"type": "integer"}}}, "consecutiveFailures": {"type": "integer"}, "createdAt": {"type": "integer"}, "updatedAt": {"type": "integer"}}}, "Error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "description": "HTTP status" }, "type": { "type": "string", "enum": [ "invalid_request", "unauthorized", "insufficient_balance", "spend_limit", "unknown_source", "run_not_found", "not_found", "method_not_allowed", "balance_reserved", "run_in_progress", "invalid_input", "too_many_runs", "rate_limited", "source_error", "unavailable", "no_results", "payment_method_not_accepted", "internal" ] }, "message": { "type": "string" }, "error": { "type": "string", "description": "Same as message (older clients)" }, "requestId": { "type": [ "string", "null" ] }, "runId": { "type": "string" }, "topUpUrl": { "type": "string" }, "available": { "type": "string" }, "minRequired": { "type": "string" }, "cost": { "type": "object", "description": "Present when a failed run was partially charged" } } }, "Whoami": { "type": "object", "properties": { "email": { "type": "string" }, "keyId": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "keyPrefix": { "type": "string" }, "wallet": { "type": "object", "properties": { "balanceMicros": { "type": "integer" }, "balance": { "type": "number" }, "balanceDisplay": { "type": "string" } } } } }, "Pricing": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "PER_CALL", "PER_RESULT" ] }, "amount": { "type": "number", "description": "USD per call or per result" }, "flatFee": { "type": "number", "description": "USD per run (per-result sources)" }, "minimum": { "type": "number", "description": "USD minimum per run" }, "maxItems": { "type": "integer" }, "currency": { "const": "USD" }, "display": { "type": "string" } } }, "Quote": { "type": "object", "properties": { "maxCharge": { "type": "number", "description": "The most this run can cost, USD" }, "maxChargeDisplay": { "type": "string" }, "maxResults": { "type": "integer" }, "needsConfirmation": { "type": "boolean", "description": "True above $0.10: ask the user before running" }, "basis": { "type": "string" }, "balanceTooLow": { "type": "boolean" }, "minBalanceToStart": { "type": "string" }, "reducedByBalance": { "type": "boolean" }, "currency": { "const": "USD" } } }, "Source": { "type": "object", "properties": { "scraper": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "bestFor": { "type": "string" }, "platform": { "type": "string" }, "pricing": { "$ref": "#/components/schemas/Pricing" }, "estimate": { "type": "object", "properties": { "per100Results": { "type": [ "number", "null" ] }, "resultsPerCall": { "type": "number" }, "basis": { "type": "string" } } }, "verdict": { "type": "string", "enum": [ "recommended", "ok", "not_recommended" ] }, "why": { "type": "string" }, "recentFailureRate": { "type": "number" } } }, "DiscoverResult": { "type": "object", "properties": { "query": { "type": "string" }, "count": { "type": "integer" }, "guide": { "type": "string" }, "note": { "type": "string" }, "recommended": { "type": "array", "items": { "type": "object" } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/Source" } } } }, "Inspect": { "allOf": [ { "$ref": "#/components/schemas/Source" }, { "type": "object", "properties": { "inputFields": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string" }, "type": { "type": "string" }, "required": { "type": "boolean" }, "description": { "type": "string" }, "default": {}, "enum": { "type": "array" }, "paging": { "type": "boolean", "description": "Pass the matching value from the previous result's page object" } } } }, "exampleInput": { "type": "object" }, "pagingNote": { "type": "string" }, "caveat": { "type": "string" }, "quote": { "$ref": "#/components/schemas/Quote" } } } ] }, "RunRequest": { "type": "object", "required": [ "scraper", "input" ], "properties": { "scraper": { "type": "string", "description": "Source id from discover" }, "input": { "type": "object", "description": "Input fields (see inspect)" }, "maxItems": { "type": "integer", "minimum": 1, "description": "Per-result sources: most results to return (default 100)" }, "timeout": { "type": "integer", "minimum": 1, "maximum": 300, "default": 300, "description": "Seconds" }, "async": { "type": "boolean", "default": false, "description": "Return 202 with a runId at once" } } }, "Cost": { "type": "object", "properties": { "type": { "type": "string" }, "amount": { "type": "number" }, "amountDisplay": { "type": "string" }, "breakdown": { "type": "string" }, "currency": { "const": "USD" } } }, "Downloads": { "type": "object", "properties": { "json": { "type": "string" }, "csv": { "type": "string" }, "xlsx": { "type": "string" } } }, "RunResult": { "type": "object", "properties": { "runId": { "type": "string" }, "items": { "type": "array", "items": {} }, "count": { "type": "integer", "description": "Records returned" }, "page": { "type": "object", "description": "Per-call sources: cursor values for the next page" }, "capped": { "type": "string", "enum": [ "default_100", "balance", "source_max", "size" ] }, "cappedNote": { "type": "string" }, "cost": { "$ref": "#/components/schemas/Cost" }, "quote": { "$ref": "#/components/schemas/Quote" }, "wallet": { "type": "object", "properties": { "balance": { "type": "number" }, "balanceDisplay": { "type": "string" } } }, "download": { "$ref": "#/components/schemas/Downloads" } } }, "RunSummary": { "type": "object", "properties": { "id": { "type": "string" }, "scraper": { "type": "string" }, "status": { "type": "string", "enum": [ "pending", "running", "success", "error" ] }, "itemsCount": { "type": [ "integer", "null" ] }, "chargedMicros": { "type": [ "integer", "null" ] }, "chargedDisplay": { "type": [ "string", "null" ] }, "duration_ms": { "type": [ "integer", "null" ] }, "error": { "type": [ "string", "null" ] }, "createdAt": { "type": "integer" }, "completedAt": { "type": [ "integer", "null" ] } } }, "Run": { "allOf": [ { "$ref": "#/components/schemas/RunSummary" }, { "type": "object", "properties": { "input": { "type": "object" }, "items": { "type": [ "array", "null" ] }, "total": { "type": "integer" }, "offset": { "type": "integer" }, "nextOffset": { "type": [ "integer", "null" ] }, "page": { "type": "object" }, "capped": { "type": "string" }, "outputExpired": { "type": "boolean", "description": "Results are kept for 30 days" }, "cost": { "$ref": "#/components/schemas/Cost" }, "quote": { "type": "object" }, "download": { "$ref": "#/components/schemas/Downloads" } } } ] } } } }