{"openapi":"3.1.0","info":{"title":"MapsData API","description":"Submit Google Maps scrapes, track them, and download the results.\n\nAuthenticate with `Authorization: Bearer <your key>`. Create a key in Settings. A scrape's `query` must be a canonical Google Maps category, so most integrations call `/categories/validate` first.","version":"1.0.0"},"paths":{"/api/v1/categories":{"get":{"tags":["MapsData API"],"summary":"Search valid Google Maps categories","description":"Search the Google Maps category taxonomy.\n\nA scrape's `query` must be one of these, so this is normally the first call\nan integration makes.","operationId":"api_categories_api_v1_categories_get","security":[{"MapsData API key":[]}],"parameters":[{"name":"q","in":"query","required":false,"schema":{"type":"string","maxLength":120,"description":"Substring to match.","default":"","title":"Q"},"description":"Substring to match."},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":20,"title":"Limit"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryList"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Not Found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Too Many Requests"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/categories/validate":{"get":{"tags":["MapsData API"],"summary":"Check whether a term is a scrapable category","description":"Resolve a term to its canonical category spelling.\n\nReturns the exact string to submit, or close suggestions when the term is\nnot a category. Calling this first is the cheapest way to avoid the most\ncommon submission rejection.","operationId":"api_categories_validate_api_v1_categories_validate_get","security":[{"MapsData API key":[]}],"parameters":[{"name":"name","in":"query","required":true,"schema":{"type":"string","minLength":1,"maxLength":120,"title":"Name"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CategoryValidation"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Not Found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Too Many Requests"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/regions":{"get":{"tags":["MapsData API"],"summary":"Valid regions for a country","description":"List the exact region names `states` accepts.\n\nSubmit these verbatim. Abbreviations are deliberately rejected rather than\nexpanded, because the postal-code tables key on the full name and a silently\nunmatched region produces an empty scrape.","operationId":"api_regions_api_v1_regions_get","security":[{"MapsData API key":[]}],"parameters":[{"name":"country","in":"query","required":false,"schema":{"type":"string","maxLength":8,"default":"us","title":"Country"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RegionList"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Not Found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Too Many Requests"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/clients":{"get":{"tags":["MapsData API"],"summary":"Clients this credential can file scrapes under","description":"List the `client_id` values this credential may use.\n\nMost workspaces have exactly one, and `client_id` can be omitted entirely\non submission. This exists so a multi-client workspace has a way to\ndiscover the ids, because `client_forbidden` is otherwise a rejection with\nno way to find the right answer.","operationId":"api_clients_api_v1_clients_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ClientList"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}},"security":[{"MapsData API key":[]}]}},"/api/v1/usage":{"get":{"tags":["MapsData API"],"summary":"Plan usage this cycle","description":"Current cycle usage and the per-scrape ceiling.\n\n`leads_used` counts rows that carried a deliverable email, which is the unit\nbilling works in. `total_limit` on a job counts rows scraped, so the two are\ndeliberately different units.","operationId":"api_usage_api_v1_usage_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}},"429":{"description":"Too Many Requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}}}},"security":[{"MapsData API key":[]}]}},"/api/v1/jobs":{"post":{"tags":["MapsData API"],"summary":"Submit a scrape","description":"Start a scrape. Returns immediately with a queued job.\n\nScrapes take minutes to hours. Poll GET /api/v1/jobs/{id} at a sensible\ninterval rather than in a tight loop; MapsData also emails you on\ncompletion.\n\nSend an `Idempotency-Key` header to make retries safe: replaying the same\nkey with the same body returns the original job instead of creating a\nsecond one.\n\nSet `dry_run: true` to validate against every gate, including the quota\ncheck, without creating a job or spending anything.","operationId":"api_create_job_api_v1_jobs_post","security":[{"MapsData API key":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ScrapeCreate"}}}},"responses":{"202":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Not Found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Too Many Requests"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}},"get":{"tags":["MapsData API"],"summary":"List scrapes","description":"Your workspace's scrapes, newest first. Keyset paginated.","operationId":"api_list_jobs_api_v1_jobs_get","security":[{"MapsData API key":[]}],"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"default":25,"title":"Limit"}},{"name":"cursor","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"next_cursor from a prior page.","title":"Cursor"},"description":"next_cursor from a prior page."},{"name":"status","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by job status.","title":"Status"},"description":"Filter by job status."}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobList"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Not Found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Too Many Requests"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}":{"get":{"tags":["MapsData API"],"summary":"Get one scrape","description":"Current state of one scrape.\n\nThis is a snapshot, not a stream. A scrape can run for hours, so poll at a\nsensible interval rather than in a loop.","operationId":"api_get_job_api_v1_jobs__job_id__get","security":[{"MapsData API key":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Not Found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Too Many Requests"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}/cancel":{"post":{"tags":["MapsData API"],"summary":"Cancel a scrape","description":"Cancel a queued or running scrape.\n\nCancelling a RUNNING scrape still bills the leads already delivered, the\nsame as in the dashboard. A queued scrape costs nothing.","operationId":"api_cancel_job_api_v1_jobs__job_id__cancel_post","security":[{"MapsData API key":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Job"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Not Found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Too Many Requests"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/api/v1/jobs/{job_id}/download":{"get":{"tags":["MapsData API"],"summary":"Get a download link","description":"A short-lived signed URL for a finished scrape's file.\n\nReturns the URL as JSON rather than redirecting to it. A 302 to a\nthird-party storage origin makes naive HTTP clients resend the\nAuthorization header cross-origin, which leaks the credential, and an agent\ngenerally wants a link to hand to a person rather than a followed redirect.\n\nThe link expires in 15 minutes. Ask for a new one rather than caching it.","operationId":"api_download_api_v1_jobs__job_id__download_get","security":[{"MapsData API key":[]}],"parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","title":"Job Id"}},{"name":"format","in":"query","required":false,"schema":{"$ref":"#/components/schemas/DownloadFormat","default":"csv"}},{"name":"scope","in":"query","required":false,"schema":{"$ref":"#/components/schemas/DownloadScope","default":"emails"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DownloadLink"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Bad Request"},"401":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Unauthorized"},"403":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Forbidden"},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Not Found"},"429":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiErrorResponse"}}},"description":"Too Many Requests"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ApiErrorBody":{"properties":{"code":{"type":"string","title":"Code"},"message":{"type":"string","title":"Message"},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field"},"details":{"additionalProperties":true,"type":"object","title":"Details"},"request_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Request Id"}},"type":"object","required":["code","message"],"title":"ApiErrorBody"},"ApiErrorResponse":{"properties":{"error":{"$ref":"#/components/schemas/ApiErrorBody"}},"type":"object","required":["error"],"title":"ApiErrorResponse","description":"Every 4xx and 5xx from /api/v1 has this shape."},"Category":{"properties":{"name":{"type":"string","title":"Name"}},"type":"object","required":["name"],"title":"Category"},"CategoryList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Category"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"CategoryList"},"CategoryValidation":{"properties":{"valid":{"type":"boolean","title":"Valid"},"canonical":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Canonical","description":"The exact spelling to submit. Casing matters."},"suggestions":{"items":{"type":"string"},"type":"array","title":"Suggestions","description":"Close matches, when the term was not recognised."}},"type":"object","required":["valid"],"title":"CategoryValidation"},"CityRef":{"properties":{"city":{"type":"string","maxLength":80,"minLength":1,"title":"City","description":"City name, e.g. 'Austin'"},"state":{"type":"string","maxLength":80,"minLength":1,"title":"State","description":"Full region name, e.g. 'Texas'. Not an abbreviation."}},"additionalProperties":false,"type":"object","required":["city","state"],"title":"CityRef","description":"A named city for Advanced Search. Re-resolved server-side against the\nseeded city index, so a city that does not exist is rejected rather than\nsilently dropped."},"Client":{"properties":{"id":{"type":"string","title":"Id"},"name":{"type":"string","title":"Name"},"is_default":{"type":"boolean","title":"Is Default","description":"True for the client used when client_id is omitted.","default":false}},"type":"object","required":["id","name"],"title":"Client","description":"A workspace's client, the label a scrape's results are filed under.\n\nOnly the id and name are exposed. The Drive folder columns are internal\nrouting for one org and mean nothing to an API caller."},"ClientList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Client"},"type":"array","title":"Data"}},"type":"object","required":["data"],"title":"ClientList"},"DownloadFlags":{"properties":{"csv":{"type":"boolean","title":"Csv","default":false},"xlsx":{"type":"boolean","title":"Xlsx","default":false},"csv_all":{"type":"boolean","title":"Csv All","default":false},"xlsx_all":{"type":"boolean","title":"Xlsx All","default":false},"filtered_csv":{"type":"boolean","title":"Filtered Csv","default":false},"filtered_xlsx":{"type":"boolean","title":"Filtered Xlsx","default":false}},"type":"object","title":"DownloadFlags","description":"Which files exist for a job. Booleans, never object keys."},"DownloadFormat":{"type":"string","enum":["csv","xlsx"],"title":"DownloadFormat"},"DownloadLink":{"properties":{"url":{"type":"string","title":"Url","description":"Short-lived signed URL. Fetch it promptly."},"expires_at":{"type":"string","format":"date-time","title":"Expires At"},"format":{"$ref":"#/components/schemas/DownloadFormat"},"scope":{"$ref":"#/components/schemas/DownloadScope"},"filename":{"type":"string","title":"Filename"}},"type":"object","required":["url","expires_at","format","scope","filename"],"title":"DownloadLink"},"DownloadScope":{"type":"string","enum":["emails","all","filtered"],"title":"DownloadScope"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"Job":{"properties":{"id":{"type":"string","title":"Id"},"status":{"type":"string","title":"Status","description":"One of: queued, running, cancelling, cancelled, completed, failed."},"progress":{"type":"integer","title":"Progress","description":"Percent complete, 0-100.","default":0},"query":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Query"},"list_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"List Name"},"country":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Country"},"states":{"items":{"type":"string"},"type":"array","title":"States"},"cities":{"items":{"additionalProperties":true,"type":"object"},"type":"array","title":"Cities"},"total_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Total Limit"},"lead_count":{"type":"integer","title":"Lead Count","description":"Rows scraped so far. Live during a run.","default":0},"email_count":{"type":"integer","title":"Email Count","description":"Rows carrying an email. Set when the job settles, and the figure your usage is billed on.","default":0},"stop_reason":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Stop Reason","description":"Why the scrape stopped. Set on essentially every completed scrape, so compare it against specific values rather than testing whether it is present. One of: 'limit_reached' (hit the requested total), 'coverage_exhausted' (covered every area selected and that was all there was), 'diminishing_returns' (results thinned out, so it stopped rather than walk the long tail), 'barren_query' (the densest areas returned almost nothing), 'user_cancel', 'stall', or 'memory_checkpoint'. The middle three all mean the area genuinely did not hold that many businesses and re-running returns the same count, so a result short of total_limit is expected rather than a failure. NULL means no reason was recorded: the scrape either finished before this field existed, or was cancelled or failed before it was set. Read it with `status`, never on its own."},"error_message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Error Message"},"export_error":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Export Error"},"created_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Created At"},"started_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Started At"},"completed_at":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Completed At"},"downloads":{"$ref":"#/components/schemas/DownloadFlags"}},"type":"object","required":["id","status"],"title":"Job"},"JobList":{"properties":{"data":{"items":{"$ref":"#/components/schemas/Job"},"type":"array","title":"Data"},"has_more":{"type":"boolean","title":"Has More","default":false},"next_cursor":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Next Cursor","description":"Pass as ?cursor= to fetch the next page."}},"type":"object","required":["data"],"title":"JobList"},"RegionList":{"properties":{"country":{"type":"string","title":"Country"},"country_name":{"type":"string","title":"Country Name"},"regions":{"items":{"type":"string"},"type":"array","title":"Regions","description":"Submit these strings verbatim. Abbreviations are rejected."}},"type":"object","required":["country","country_name","regions"],"title":"RegionList"},"ScrapeCreate":{"properties":{"query":{"type":"string","maxLength":300,"minLength":1,"title":"Query","description":"One to three comma-separated Google Maps categories, e.g. 'Plumber' or 'Plumber, Electrician'."},"country":{"type":"string","title":"Country","description":"One of us, au, uk, ca.","default":"us"},"states":{"items":{"type":"string"},"type":"array","maxItems":200,"title":"States","description":"Full region names for the chosen country, e.g. ['Texas']. Abbreviations are rejected. Omit when passing `cities`."},"cities":{"items":{"$ref":"#/components/schemas/CityRef"},"type":"array","maxItems":50,"title":"Cities","description":"Named cities instead of whole regions. Max 50."},"total_limit":{"type":"integer","minimum":1.0,"title":"Total Limit","description":"Rows to scrape. Capped by your plan's per-scrape ceiling; see GET /api/v1/usage."},"max_emails_per_company":{"anyOf":[{"type":"integer","minimum":1.0},{"type":"null"}],"title":"Max Emails Per Company","description":"Cap emails kept per business. Omit for no cap."},"min_reviews":{"type":"integer","minimum":0.0,"title":"Min Reviews","description":"Skip businesses with fewer reviews.","default":0},"max_reviews":{"anyOf":[{"type":"integer","minimum":0.0},{"type":"null"}],"title":"Max Reviews","description":"Skip businesses with more reviews."},"list_name":{"anyOf":[{"type":"string","maxLength":120},{"type":"null"}],"title":"List Name","description":"Label for this list. Defaults to the query."},"client_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Client Id","description":"Only for multi-client workspaces. Defaults to your Main client."},"include_variants":{"type":"boolean","title":"Include Variants","description":"Also search up to four closely related categories, which typically finds materially more unique businesses. Applies only to single-category submissions: with two or three categories your own terms already occupy the fan-out. Set false to search the exact category only.","default":true},"dry_run":{"type":"boolean","title":"Dry Run","description":"Validate against every gate and return the resolved plan WITHOUT creating a job or spending any quota.","default":false}},"additionalProperties":false,"type":"object","required":["query","total_limit"],"title":"ScrapeCreate","description":"A new scrape job.\n\n`query` must match a canonical Google Maps category. Call\nGET /api/v1/categories/validate first if you are unsure: an unrecognised\nquery is the single most common reason a submission is rejected, and the\nerror carries suggestions."},"Usage":{"properties":{"organization_id":{"type":"string","title":"Organization Id"},"plan_tier":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Plan Tier"},"leads_used":{"type":"integer","title":"Leads Used"},"lead_limit":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Lead Limit","description":"Total available this cycle including bonuses. null means unlimited."},"leads_remaining":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Leads Remaining","description":"null when the limit is unlimited."},"max_leads_per_scrape":{"type":"integer","title":"Max Leads Per Scrape"},"can_submit":{"type":"boolean","title":"Can Submit","description":"False when this cycle's allowance is spent."}},"type":"object","required":["organization_id","leads_used","max_leads_per_scrape","can_submit"],"title":"Usage"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer"}}},"security":[{"bearerAuth":[]}]}