{ "openapi": "3.1.0", "info": { "title": "Glasser", "version": "0.0.1", "description": "One key, no contract, pay per call, across paid APIs bought wholesale. Every response carries x-request-id; every error body carries the same envelope." }, "paths": { "/v1/solutions/gtm/web_research": { "post": { "tags": [ "Solutions" ], "operationId": "gtm-web-research", "parameters": [ { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "minLength": 1, "description": "Generate a unique value for each intended execution (a UUID is recommended). Retry with the same key and execution parameters to retrieve the original Run without a second charge. Changing execution parameters with the same key returns 409; changing task_id or metadata does not update the original Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WebResearchResult" } ] } } } }, "202": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/WebResearchResult" } ] } } } }, "400": { "description": "ValidationFailed | IdempotencyKeyRequired", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/IdempotencyKeyRequiredEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "402": { "description": "InsufficientBalance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientBalanceEncoded" } } } }, "403": { "description": "EndpointNotPermitted | Forbidden", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EndpointNotPermittedEncoded" }, { "$ref": "#/components/schemas/ForbiddenEncoded" } ] } } } }, "409": { "description": "IdempotencyConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyConflictEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } }, "503": { "description": "ServiceUnavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableEncoded" } } } } }, "description": "Search and retrieve public web content. Every action returns normalized output with the last Run's id, provider and lifecycle status: search gives output.results[], news / places / scholar / shopping / images / videos / similar give output.items[] with fixed fields per row, answer gives output.answer plus citations[], and scrape gives fixed content fields.\n\nFor scrape, read output.text, output.markdown, output.html and output.raw_html. Missing formats are null; no HTML-to-text conversion is performed. The Provider's native output is not repeated in output; read it from the Run with GET /v1/runs/:id. For search, read output.results[].\n\nRead result_status separately from status: success, partial, no_result, error or pending. COMPLETED means the final Run settled with a Provider response; it does not prove usable content. output is null on delivery failure or while pending. partial lists missing_formats. Content semantics remain unverified; text wording and length do not judge quality.\n\ncharge_usd is the total of this response's runs, including paid failures and empty results. It is null until every listed Run settles. runs[] contains individual charges, statuses and charge_basis without duplicate bodies. A multi-Run total has charge_basis=null. The response is a Solution result, not the stored Run. GET /v1/runs/:id remains native and has an individual charge.\n\nFor QUEUED/RUNNING (HTTP 202), poll the authenticated result_url on the API origin. That read returns the same normalized contract and total, creates no Runs and does not resume fallback. Terminal results return HTTP 200, including business errors; inspect result_status and error. Reuse the same Idempotency-Key and execution parameters for an intentional retry.\n\nScrape auto uses Serper then Firecrawl within a default 30000 ms request budget. HTML or explicit cache age goes directly to Firecrawl. X/Twitter and LinkedIn enrichment exclude Firecrawl; Exa and DataForSEO are explicit-only. A named Provider never falls back. Empty/invalid output, Provider errors, timeout and missing supported formats can trigger fallback when another route can improve delivery. No cross-Provider content merge. If no Run is admitted, return the admission error.\n\nWhen formats is omitted, Serper/Exa check text and Firecrawl/DataForSEO check markdown; all available native formats are mapped into output. max_charge_usd covers all Runs in this request, including replays. Budgets are held only in request memory; retrying starts a new time window but cannot change an existing Run deadline.\n\nSearch time_range supports day, week, month and year. Auto selects a Provider that supports the filter. Empty search results do not trigger paid fallback.", "summary": "Web research", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "enum": [ "search", "news", "places", "scholar", "shopping", "images", "videos", "answer", "scrape", "similar" ], "description": "Default: search.\n\n- Supply query for search, news, places, scholar, shopping, images, videos, or answer.\n- Supply url for scrape or similar." }, { "type": "null" } ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "auto", "serper", "serpapi", "exa", "dataforseo", "firecrawl" ], "description": "Default auto: select the first eligible Provider in Glasser's preference order. A named Provider must support the request and be allowed by your Key; it does not fall back to another Provider. Available values are listed below." }, { "type": "null" } ] }, "query": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048 }, { "type": "null" } ] }, "formats": { "type": "array", "items": { "type": "string", "enum": [ "text", "markdown", "html", "raw_html" ] }, "minItems": 1, "maxItems": 4, "description": "For scrape only. When omitted, use the selected Provider's native default: text for Serper/Exa, markdown for Firecrawl/DataForSEO. Requested formats guide routing and fallback; output exposes fixed text/markdown/html/raw_html fields. html means cleaned HTML; raw_html means original HTML. Auto uses Serper then Firecrawl. HTML requests go directly to Firecrawl. Read result_status and missing_formats for delivery; an unrequested null field is not a partial result. Firecrawl does not supply text; Glasser does not convert HTML to text. X/Twitter and enrichment routes are excluded from Firecrawl." }, "timeout_ms": { "type": "integer", "minimum": 1000, "maximum": 120000, "description": "For scrape only. Default 30000. Execution budget for this API request, including serial fallback. A retry has a new request window and reuses existing Runs through Run idempotency. Firecrawl and Exa use the actual remaining time, reserving settlement and response time; less than 1 second of call time is refused." }, "max_charge_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats.", "allOf": [ { "pattern": "^\\d{1,12}\\.", "description": "For scrape only. Maximum total Charge for Runs in this request, including replayed Runs. Before a new Run, settled Charges plus its maximum Charge must fit. An unsettled Run stops fallback. Omit for no caller cap; 0.00 allows no new paid Runs." } ] }, "cache_max_age_seconds": { "type": "integer", "minimum": 0, "maximum": 2592000, "description": "For scrape only. Maximum Provider cache age; 0 requires a live fetch. Routes without this control are excluded. Auto selects Firecrawl (milliseconds); explicit Exa receives whole hours rounded down. Unknown cache/fetch metadata remains null." }, "time_range": { "type": "string", "enum": [ "day", "week", "month", "year" ], "description": "For search only: restrict results to the past day, week, month, or year using Google's time filter. Omit for any time. Auto uses only Providers that support this filter (Serper and SerpApi). Exa is refused when this field is supplied. This is a search-engine filter, not a verified publication date." }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 60, "description": "Country for search-type actions, as a two-letter ISO code or a country name. Default us. Not for scrape or similar. Refused with 400 when the named provider cannot apply it." }, { "type": "null" } ] }, "language": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z]{2}$", "description": "Language for search-type actions, two letters such as en, de. Not for scrape or similar." }, { "type": "null" } ] }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100, "description": "Rows to return. Keep it small: the routed Endpoint's charge rule may read it. Each capability caps it further." }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string", "description": "Group related Runs, including automatic fallback, under one Task. Reuse a stable string and filter the Runs list by task to retrieve them." }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } }, {} ], "description": "Optional tracking fields, returned on the Run and available as filters. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name.\n\nInvalid entries are dropped whole, not truncated. The request continues, and the Run returns the fields that were stored." }, { "type": "null" } ] } }, "additionalProperties": false } } }, "required": true }, "x-mint": { "metadata": { "title": "Web research", "description": "Search the web, news, places, and other public content, retrieve a page, or get an answer with sources. Choose an action and supply a query or URL as described below." }, "content": "Every action returns normalized `output`; check `result_status` for delivery. News, places, scholar, shopping, images, videos and similar expose `output.items[]` with fixed fields per row; answer exposes `output.answer` and `citations[]`. Scrape exposes `text`, `markdown`, `html`, and `raw_html`; missing formats are null. The Provider's native output is not repeated in `output`; it stays on the Run and is readable with [Get Run](/api-reference/runs/get). Glasser does not convert HTML to text or judge semantic quality from wording or length. Search returns `output.results[]` and supports `time_range: day | week | month | year`. An empty but valid answer is `no_result` and keeps the action's shape: `results` or `items` is `[]`, and an empty answer is `answer: null` with `citations: []`. Scrape has no empty answer: a page that cannot be delivered is `error`, with `output: null` and the reason in `error.code`.\n\nFetch (`scrape`) uses Serper then Firecrawl within a default 30-second request budget. HTML or explicit cache-age requests go directly to Firecrawl. X/Twitter and LinkedIn enrichment exclude Firecrawl. A named Provider never falls back. Empty or invalid output, Provider errors, timeout, or missing supported formats can trigger fallback. The delivered content comes from the final Run; content from different captures is not merged.\n\n`charge_usd` totals this response's `runs`, including charged failures and empty results, and is null until all Runs settle. The final Run's lifecycle remains in `status`; `COMPLETED` alone does not prove content delivery. For pending work, follow the authenticated [result_url](/api-reference/solutions/gtm/web_research/result) to retain normalized output and total charges. [Get Run](/api-reference/runs/get) remains native and reports an individual charge.\n\nPolling creates no Runs and does not resume fallback. An intentional POST retry uses the same Idempotency-Key and execution parameters, reuses existing Runs, and starts a new request time window. See [Provider selection and charges](/api-reference/solutions/overview#how-provider-selection-works).\n\n## Output by action\n\nEvery field is present on every row; a value the Provider does not report is `null`. Fields follow the [field conventions](/api-reference/solutions/overview#field-conventions).\n\n| action | `output` |\n| --- | --- |\n| `search` | `results[]`: url, title, snippet, position, published_at, date_text, date (deprecated) |\n| `news` | `items[]`: title, url, source, published_at, date_text, snippet |\n| `places` | `items[]`: name, address, category, rating, reviews, phone, website, latitude, longitude, google_cid |\n| `scholar` | `items[]`: title, url, snippet, publication, year, cited_by, pdf_url |\n| `shopping` | `items[]`: title, url (Google Shopping page), merchant_url, google_product_id, price_text, seller, rating, reviews, image_url |\n| `images` | `items[]`: title, image_url, thumbnail_url, source_url, source, width, height |\n| `videos` | `items[]`: title, url, channel, source, date_text, duration_text, snippet, thumbnail_url |\n| `answer` | answer, `citations[]`: url, title, published_at |\n| `scrape` | url, final_url, title, text, markdown, html, raw_html, text_character_limit, cached, fetched_at, quality (deprecated) |\n| `similar` | `items[]`: url, title, exa_similarity_score, published_at, author |\n\n- `published_at` is an ISO 8601 UTC timestamp, filled only when the Provider reports a machine timestamp (Exa `publishedDate`, SerpApi news `iso_date`). `fetched_at` is the same format.\n- `date_text` is Google's display text exactly as returned. It may be relative to the Run's `completed_at` (\"3 hours ago\") and is never parsed.\n- search `date` is deprecated: it holds Google's display text for Serper and SerpApi and Exa's raw `publishedDate` for Exa. Use `published_at` or `date_text`.\n- `snippet` is Google's short excerpt, or Exa's extracted highlight for Exa; it is never the full page text.\n- `price_text` and `duration_text` are display strings, not parsed; the price currency follows `country`.\n- `rating` is Google's 1–5 star average and `reviews` is a count. `source` is a publisher or site name.\n- `address` is the Provider's own text; Serper may return only the street line.\n- `exa_similarity_score` is Exa's own score, comparable only within one response. Similar leaves out pages from the requested URL's host.\n- `text_character_limit` is the character cap Glasser asked the Provider to apply (10000 for Exa); text of exactly that length may be truncated. `cached` says whether the Provider served the page from its cache.\n- `quality` is always `unverified` and will be removed in the next breaking revision.\n\n```json\n{\n \"action\": \"news\",\n \"provider\": \"serper\",\n \"status\": \"COMPLETED\",\n \"result_status\": \"success\",\n \"output\": {\n \"items\": [\n { \"title\": \"Ripple, Stripe-owned Privy partner to bring embedded wallets to XRP Ledger\", \"url\": \"https://www.theblock.co/news/business/2026-10-13-stripe-privy-ripple-xrp-ledger-wallets-418463\", \"source\": \"The Block\", \"published_at\": null, \"date_text\": \"18 hours ago\", \"snippet\": \"The integration will allow developers to add XRP Ledger wallets to their apps using Privy's infrastructure.\" }\n ]\n },\n \"charge_usd\": \"0.0011\",\n \"runs\": [{ \"provider\": \"serper\", \"status\": \"COMPLETED\", \"charge_usd\": \"0.0011\" }],\n \"result_url\": \"/v1/solutions/gtm/web_research/result?token=…\"\n}\n```", "href": "/api-reference/solutions/gtm/web_research" } } }, "/v1/solutions/gtm/web_research/result": { "get": { "tags": [ "Solutions" ], "operationId": "gtm-web-research-result", "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "Opaque result context returned in result_url. Keep it unchanged and authenticate with a Key permitted to read every listed Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "WebResearchResult", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebResearchResult" } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Follow result_url from search or scrape to read normalized output, business result_status and the total charge of the same Runs. HTTP 200 may still contain result_status=pending. This authenticated read creates no Runs, calls no Providers and does not resume fallback or reset budgets. GET /v1/runs/:id remains the native individual Run. The result context is signed, bound to the Workspace and checked against the current Key policy for every Run.", "summary": "Read a web research result", "x-mint": { "metadata": { "title": "Read a web research result", "description": "Read normalized output, delivery status, and total charges for an existing Web research request. Follow the result_url returned by every web_research action." }, "content": "Use `result_url` unchanged on the API origin and authenticate with a Key permitted to read every Run. The response uses the same fields as the initial Solution response. HTTP 200 can still contain `result_status: pending`; continue polling until the final Run is terminal.\n\nThis is a read-only request. It creates no Runs, calls no Providers, and does not resume fallback or reset the execution budget. [Get Run](/api-reference/runs/get) remains the separate API for native output and an individual Run's charge.", "href": "/api-reference/solutions/gtm/web_research/result" } } }, "/v1/solutions/gtm/company_intelligence": { "post": { "tags": [ "Solutions" ], "operationId": "gtm-company-intelligence", "parameters": [ { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "minLength": 1, "description": "Generate a unique value for each intended execution (a UUID is recommended). Retry with the same key and execution parameters to retrieve the original Run without a second charge. Changing execution parameters with the same key returns 409; changing task_id or metadata does not update the original Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CompanyIntelligenceResult" } ] } } } }, "202": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/CompanyIntelligenceResult" } ] } } } }, "400": { "description": "ValidationFailed | IdempotencyKeyRequired", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/IdempotencyKeyRequiredEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "402": { "description": "InsufficientBalance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientBalanceEncoded" } } } }, "403": { "description": "EndpointNotPermitted | Forbidden", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EndpointNotPermittedEncoded" }, { "$ref": "#/components/schemas/ForbiddenEncoded" } ] } } } }, "409": { "description": "IdempotencyConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyConflictEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } }, "503": { "description": "ServiceUnavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableEncoded" } } } } }, "description": "Look up a company by domain: profile and firmographics, technology stack, website traffic, similar businesses, funding history and news. Choose an action and supply the domain.\n\nEvery action returns normalized output with the last Run's id, provider and lifecycle status: enrich and traffic give fixed top-level fields, tech_stack / competitors / news give output.items[] with fixed fields per row, funding gives total_funding_usd plus items[]. The Provider's native output is not repeated in output; it stays on the Run and is readable with GET /v1/runs/:id. A value the selected Provider does not report is null; money is always USD.\n\nRead result_status separately from status: success, no_result, error or pending. charge_usd is the total of this response's runs and is null until every listed Run settles; runs[] carries each Run's charge. provider=auto selects the first eligible Provider and tries the next only on PROVIDER_ERROR, TIMED_OUT, or a 503 at admission; a named Provider never falls back. For QUEUED/RUNNING (HTTP 202, today only traffic via Apify), poll the authenticated result_url on the API origin. Reuse the same Idempotency-Key and execution parameters for an intentional retry.", "summary": "Company intelligence", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "enum": [ "enrich", "tech_stack", "traffic", "competitors", "funding", "news" ], "description": "Default: enrich. All actions require domain.\n\n- enrich: company profile and firmographics.\n- tech_stack, traffic, funding, news: the corresponding company data.\n- competitors: similar businesses. For competing domains in Google results, use SEO research with organic_competitors." }, { "type": "null" } ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "auto", "apollo", "pdl", "hunter", "prospeo", "predictleads", "leadmagic", "builtwith", "dataforseo", "ahrefs", "apify", "exa", "serper" ], "description": "Default auto: select the first eligible Provider in Glasser's preference order. A named Provider must support the request and be allowed by your Key; it does not fall back to another Provider. Available values are listed below." }, { "type": "null" } ] }, "domain": { "type": "string", "minLength": 3, "maxLength": 253, "description": "A website domain such as stripe.com. A full URL is accepted and reduced to its host." }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 60, "description": "Country as a two-letter ISO code or a country name, e.g. us, gb, de, Germany. Default us. An unsupported country is refused with the supported list." }, { "type": "null" } ] }, "query": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200, "description": "For news via Serper only: the company name to search Google News by, instead of the domain. Other actions and providers ignore it." }, { "type": "null" } ] }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100, "description": "Rows to return. Keep it small: the routed Endpoint's charge rule may read it. Each capability caps it further." }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string", "description": "Group related Runs, including automatic fallback, under one Task. Reuse a stable string and filter the Runs list by task to retrieve them." }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } }, {} ], "description": "Optional tracking fields, returned on the Run and available as filters. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name.\n\nInvalid entries are dropped whole, not truncated. The request continues, and the Run returns the fields that were stored." }, { "type": "null" } ] } }, "required": [ "domain" ], "additionalProperties": false } } }, "required": true }, "x-mint": { "metadata": { "title": "Company intelligence", "description": "Look up a company by domain: profile, technology stack, website traffic, similar businesses, funding and news, with one normalized output across Providers." }, "content": "Every action returns normalized `output`. The Provider's native output is not repeated there; it stays on the Run and is readable with [Get Run](/api-reference/runs/get). `enrich` and `traffic` expose fixed top-level fields; `tech_stack`, `competitors` and `news` expose `output.items[]`; `funding` exposes `total_funding_usd` plus `items[]`. A value the selected Provider does not report is `null`; Glasser does not fill it in. Money is always USD.\n\nRead `result_status` separately from `status`: `success`, `no_result`, `error` or `pending`. An empty but valid answer is `no_result` and keeps the action's shape: every field is `null`, or `items` is `[]`. `charge_usd` totals this response's `runs` and is null until all Runs settle. With `provider: auto`, fallback can create multiple Runs, each listed in `runs[]` with its own charge. For a pending Similarweb lookup (`traffic` via Apify, HTTP 202), follow the authenticated [result_url](/api-reference/solutions/gtm/company_intelligence/result). See [Provider selection and charges](/api-reference/solutions/overview#how-provider-selection-works).\n\n## Output by action\n\nEvery field is present on every row; a value the Provider does not report is `null`. Fields follow the [field conventions](/api-reference/solutions/overview#field-conventions).\n\n| action | `output` |\n| --- | --- |\n| `enrich` | name, website, description, industry, employees, employee_range_min, employee_range_max, founded_year, city, region, country, country_code, linkedin_url, phone, total_funding_usd, revenue_usd, revenue_range_min_usd, revenue_range_max_usd, ownership, ticker, latest_funding_date |\n| `tech_stack` | `items[]`: name, categories[], detection_source, predictleads_confidence, first_detected_date, last_detected_date |\n| `traffic` | monthly_visits, organic_traffic, paid_traffic, organic_keywords, paid_keywords, organic_traffic_value_usd, similarweb_global_rank, bounce_rate, pages_per_visit, avg_visit_duration_seconds |\n| `competitors` | `items[]`: domain, name, page_title, position, predictleads_similarity_score, exa_similarity_score, reason |\n| `funding` | total_funding_usd, `items[]`: round_date, round, amount_usd, investors[], source_url |\n| `news` | `items[]`: title, url, source, published_at, event_date, date_text, category, snippet |\n\n- `employees` and the revenue fields are the Provider's own estimates. `revenue_usd` is a single figure; when a Provider only gives a bucket, it is `null` and the bucket edges are in `revenue_range_min_usd` / `revenue_range_max_usd`. `employee_range_min` / `employee_range_max` work the same way. An open-ended bucket such as `10000+` has a `null` maximum.\n- `country` is an English display name and `country_code` an ISO 3166-1 alpha-2 code. `ownership` is one of `public`, `private`, `nonprofit`, `government`, `education`, `other`, or `null`; private is never inferred.\n- Scores from a Provider's own model carry its name and are `null` for the others: `predictleads_similarity_score` (0–1), `exa_similarity_score` (Exa's neural similarity), `predictleads_confidence` (0–1), `similarweb_global_rank` (1 = most visited). `position` is the 1-based order in the Provider's answer.\n- competitors via Exa returns web pages, not company records: `name` is `null` and the page title is in `page_title`. Rows from the company's own domain and its subdomains are left out.\n- `monthly_visits` is worldwide (Similarweb). `organic_traffic`, `paid_traffic` and the keyword counts are for the request `country` (default `us`). `bounce_rate` is a fraction 0–1.\n- Dates: `*_date` and `event_date` are `YYYY-MM-DD`, `published_at` is ISO 8601 UTC, and `date_text` is Google News display text exactly as returned. LeadMagic funding dates have month precision (day `01`).\n- `industry`, `categories`, `round` and `category` are labels in the answering Provider's own vocabulary and are not comparable across Providers.\n\n```json\n{\n \"action\": \"enrich\",\n \"provider\": \"apollo\",\n \"status\": \"COMPLETED\",\n \"result_status\": \"success\",\n \"output\": {\n \"name\": \"Stripe\", \"website\": \"http://www.stripe.com\", \"industry\": \"information technology & services\",\n \"employees\": 9400, \"employee_range_min\": null, \"employee_range_max\": null, \"founded_year\": 2010,\n \"city\": \"South San Francisco\", \"region\": \"California\", \"country\": \"United States\", \"country_code\": \"US\",\n \"linkedin_url\": \"http://www.linkedin.com/company/stripe\", \"phone\": \"+1 415-298-5539\",\n \"total_funding_usd\": 9443867423, \"revenue_usd\": 6935000000, \"revenue_range_min_usd\": null, \"revenue_range_max_usd\": null,\n \"ownership\": null, \"ticker\": null, \"latest_funding_date\": \"2026-03-01\",\n \"description\": \"Stripe, Inc. is a global financial technology company…\"\n },\n \"charge_usd\": \"0.026\",\n \"runs\": [{ \"provider\": \"apollo\", \"status\": \"COMPLETED\", \"charge_usd\": \"0.026\" }],\n \"result_url\": \"/v1/solutions/gtm/company_intelligence/result?token=…\"\n}\n```", "href": "/api-reference/solutions/gtm/company_intelligence" } } }, "/v1/solutions/gtm/company_intelligence/result": { "get": { "tags": [ "Solutions" ], "operationId": "gtm-company-intelligence-result", "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "Opaque result context returned in result_url. Keep it unchanged and authenticate with a Key permitted to read every listed Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "CompanyIntelligenceResult", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIntelligenceResult" } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Follow result_url from a company intelligence call to read normalized output, business result_status and the total charge of the same Runs. HTTP 200 may still contain result_status=pending. This authenticated read creates no Runs, calls no Providers and does not resume fallback. GET /v1/runs/:id remains the native individual Run. The result context is signed, bound to the Workspace and checked against the current Key policy for every Run.", "summary": "Read a company intelligence result", "x-mint": { "metadata": { "title": "Read a company intelligence result", "description": "Read normalized output, delivery status, and total charges for an existing company intelligence request. Follow the result_url returned by the call." }, "content": "Use `result_url` unchanged on the API origin and authenticate with a Key permitted to read every Run. The response uses the same fields as the initial Solution response. HTTP 200 can still carry `result_status: pending` while an asynchronous lookup runs; keep polling until `status` is terminal. This read creates no Runs, calls no Providers and does not resume fallback.", "href": "/api-reference/solutions/gtm/company_intelligence/result" } } }, "/v1/solutions/gtm/people_search": { "post": { "tags": [ "Solutions" ], "operationId": "gtm-people-search", "parameters": [ { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "minLength": 1, "description": "Generate a unique value for each intended execution (a UUID is recommended). Retry with the same key and execution parameters to retrieve the original Run without a second charge. Changing execution parameters with the same key returns 409; changing task_id or metadata does not update the original Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PeopleSearchResult" } ] } } } }, "202": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/PeopleSearchResult" } ] } } } }, "400": { "description": "ValidationFailed | IdempotencyKeyRequired", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/IdempotencyKeyRequiredEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "402": { "description": "InsufficientBalance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientBalanceEncoded" } } } }, "403": { "description": "EndpointNotPermitted | Forbidden", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EndpointNotPermittedEncoded" }, { "$ref": "#/components/schemas/ForbiddenEncoded" } ] } } } }, "409": { "description": "IdempotencyConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyConflictEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } }, "503": { "description": "ServiceUnavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableEncoded" } } } } }, "description": "Find people by job title, seniority, location, or employer. You can also enrich a known person's profile or find their work email. Choose an action and supply its required fields below.\n\nEvery action returns normalized output with the last Run's id, provider and lifecycle status: search gives total_matches plus output.items[] of people, enrich and find_email give one person with the same fields at the top level. The Provider's native output is not repeated in output; it stays on the Run and is readable with GET /v1/runs/:id. A value the selected Provider does not report is null.\n\nRead result_status separately from status: success, no_result, error or pending. charge_usd is the total of this response's runs and is null until every listed Run settles; runs[] carries each Run's charge. provider=auto selects the first eligible Provider and tries the next only on PROVIDER_ERROR, TIMED_OUT, or a 503 at admission; a named Provider never falls back. Reuse the same Idempotency-Key and execution parameters for an intentional retry.", "summary": "People search", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "enum": [ "search", "enrich", "find_email" ], "description": "Default: search.\n\n- search: supply at least one of job_titles, seniorities, locations, company_domain, or keywords. Apollo and ZoomInfo rows carry no email or phone; PDL rows are full records; Hunter lists the personal addresses at company_domain.\n- enrich: supply linkedin_url, email, or full_name plus company_domain. Prospeo returns only people it holds a verified work email for.\n- find_email: supply full_name and company_domain. Apollo also accepts linkedin_url alone; an Apollo match without a real email is a miss and is not charged.\n\nFilters are never silently dropped. With auto, Providers that cannot apply them are skipped; a named Provider that cannot apply them returns 400." }, { "type": "null" } ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "auto", "apollo", "pdl", "leadmagic", "zoominfo", "hunter", "prospeo" ], "description": "Default auto: select the first eligible Provider in Glasser's preference order. A named Provider must support the request and be allowed by your Key; it does not fall back to another Provider. Available values are listed below." }, { "type": "null" } ] }, "job_titles": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 20, "description": "Job titles to match. PDL matches each title exactly as given, so 'CTO' does not match 'Co-founder & CTO'." }, { "type": "null" } ] }, "seniorities": { "anyOf": [ { "type": "array", "items": { "type": "string", "enum": [ "owner", "founder", "c_suite", "partner", "vp", "head", "director", "manager", "senior", "entry", "intern" ] }, "minItems": 1, "maxItems": 11, "description": "Seniority levels, one or more of owner, founder, c_suite, partner, vp, head, director, manager, senior, entry, intern. A Provider without a matching level returns 400 when named and is skipped under auto. ZoomInfo has no founder, owner, partner, head, entry or intern level; its senior is the whole Non Manager tier, which also includes junior individual contributors." }, { "type": "null" } ] }, "locations": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 20, "description": "Locations as free text. PDL matches each as a substring of the person's location name, so 'london' also matches 'new london, connecticut'." }, { "type": "null" } ] }, "company_domain": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 253, "description": "A website domain such as stripe.com. A full URL is accepted and reduced to its host." }, { "type": "null" } ] }, "keywords": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300 }, { "type": "null" } ] }, "full_name": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 200 }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string", "maxLength": 320, "pattern": "^[^\\s@]+@[^\\s@]+\\.[^\\s@]+$", "description": "An email address." }, { "type": "null" } ] }, "linkedin_url": { "anyOf": [ { "type": "string", "maxLength": 2048, "pattern": "linkedin\\.com\\/in\\/[^/?#\\s]+", "description": "The person's LinkedIn profile URL, linkedin.com/in/. Not a company page." }, { "type": "null" } ] }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100, "description": "Rows to return. Keep it small: the routed Endpoint's charge rule may read it. Each capability caps it further." }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string", "description": "Group related Runs, including automatic fallback, under one Task. Reuse a stable string and filter the Runs list by task to retrieve them." }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } }, {} ], "description": "Optional tracking fields, returned on the Run and available as filters. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name.\n\nInvalid entries are dropped whole, not truncated. The request continues, and the Run returns the fields that were stored." }, { "type": "null" } ] } }, "additionalProperties": false } } }, "required": true }, "x-mint": { "metadata": { "title": "People search", "description": "Find people by job title, seniority, location, or employer. You can also enrich a known person's profile or find their work email. Choose an action and supply its required fields below." }, "content": "Every action returns normalized `output`. The Provider's native output is not repeated there; it stays on the Run and is readable with [Get Run](/api-reference/runs/get). `search` returns `total_matches` and `output.items[]`, one row per person. `enrich` and `find_email` return one person with the same fields at the top level. A value the selected Provider does not report is `null`; Glasser does not fill it in.\n\nRead `result_status` separately from `status`: `success`, `no_result`, `error` or `pending`. An empty but valid answer is `no_result` and keeps the action's shape: every field is `null`, or `items` is `[]`. `find_email` without an email is `no_result`. `charge_usd` totals this response's `runs` and is null until all Runs settle. With `provider: auto`, fallback can create multiple Runs, each listed in `runs[]` with its own charge. See [Provider selection and charges](/api-reference/solutions/overview#how-provider-selection-works).\n\n## Output by action\n\nEvery field is present on every row; a value the Provider does not report is `null`. Fields follow the [field conventions](/api-reference/solutions/overview#field-conventions).\n\n| action | `output` |\n| --- | --- |\n| `search` | total_matches, `items[]`: one person per row |\n| `enrich` | one person |\n| `find_email` | one person |\n\nA person has these fields: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score.\n\n- Names, job titles and labels are as the Provider reports them. PDL names are lower case. `name` is `null` when the Provider gives only first and last name; Glasser does not join them. Apollo search masks the last name, so `last_name` is `null`.\n- `seniority` and `department` are labels in the answering Provider's own vocabulary (for example Apollo `founder`, PDL `cxo`, LeadMagic `C-Team`). They are not the request's `seniorities` values and are not comparable across Providers.\n- `email` is the address the Provider gives as the work email. PDL fills it only from `work_email`; its other addresses stay on the Run. Apollo, ZoomInfo and LeadMagic search rows have no email.\n- `email_status` is the Provider's own verification label (`verified`, `VERIFIED`, `valid`). Providers verify in different ways, so do not compare the labels. Read them with `email_catch_all` (the domain accepts every address, so a mailbox check cannot confirm this one) and `email_source` (Hunter: `found` on the web, or `generated` from the domain's address pattern). Hunter charges for a generated address.\n- `total_matches` counts the matches in the Provider's whole dataset, not only this page. It is `null` for LeadMagic, which gives only the page count.\n- Scores from a Provider's own model carry its name and are `null` for the others: `apollo_match_confidence` (high, medium, low, none), `pdl_likelihood` (1–10), `hunter_email_score` (0–100), `zoominfo_accuracy_score` (0–100).\n\n```json\n{\n \"action\": \"find_email\",\n \"provider\": \"hunter\",\n \"status\": \"COMPLETED\",\n \"result_status\": \"success\",\n \"output\": {\n \"name\": null, \"first_name\": \"Avery\", \"last_name\": \"Example\", \"job_title\": null,\n \"email\": \"example@stripe.com\", \"email_status\": \"valid\", \"email_catch_all\": true, \"email_source\": \"generated\",\n \"company_name\": \"Stripe\", \"company_domain\": \"stripe.com\", \"hunter_email_score\": 80, \"…\": \"other fields null\"\n },\n \"charge_usd\": \"0.0245\",\n \"runs\": [{ \"provider\": \"hunter\", \"status\": \"COMPLETED\", \"charge_usd\": \"0.0245\" }],\n \"result_url\": \"/v1/solutions/gtm/people_search/result?token=…\"\n}\n```\n\n## Filters\n\n- PDL matches `job_titles` exactly as given, so \"CTO\" does not match \"Co-founder & CTO\". It matches `locations` as a substring, so \"london\" also matches \"new london, connecticut\".\n- ZoomInfo has no `founder`, `owner`, `partner`, `head`, `entry` or `intern` level, so with `auto` those requests skip ZoomInfo. ZoomInfo's `senior` is its whole \"Non Manager\" tier, which also includes junior individual contributors.\n- Hunter search lists only the personal addresses at `company_domain`, not role mailboxes such as info@. Prospeo enrich returns only people it holds a verified work email for. find_email via Apollo also accepts `linkedin_url` on its own; an Apollo match without a real email is a miss and is not charged.", "href": "/api-reference/solutions/gtm/people_search" } } }, "/v1/solutions/gtm/people_search/result": { "get": { "tags": [ "Solutions" ], "operationId": "gtm-people-search-result", "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "Opaque result context returned in result_url. Keep it unchanged and authenticate with a Key permitted to read every listed Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "PeopleSearchResult", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PeopleSearchResult" } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Follow result_url from a people search call to read normalized output, business result_status and the total charge of the same Runs. This authenticated read creates no Runs, calls no Providers and does not resume fallback. GET /v1/runs/:id remains the native individual Run. The result context is signed, bound to the Workspace and checked against the current Key policy for every Run.", "summary": "Read a people search result", "x-mint": { "metadata": { "title": "Read a people search result", "description": "Read normalized output, delivery status, and total charges for an existing people search request. Follow the result_url returned by the call." }, "content": "Use `result_url` unchanged on the API origin and authenticate with a Key permitted to read every Run. The response uses the same fields as the initial Solution response. This read creates no Runs, calls no Providers and does not resume fallback. The link carries the action and the Runs, not the names, emails or other values you searched for.", "href": "/api-reference/solutions/gtm/people_search/result" } } }, "/v1/solutions/gtm/seo_research": { "post": { "tags": [ "Solutions" ], "operationId": "gtm-seo-research", "parameters": [ { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "minLength": 1, "description": "Generate a unique value for each intended execution (a UUID is recommended). Retry with the same key and execution parameters to retrieve the original Run without a second charge. Changing execution parameters with the same key returns 409; changing task_id or metadata does not update the original Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SeoResearchResult" } ] } } } }, "202": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SeoResearchResult" } ] } } } }, "400": { "description": "ValidationFailed | IdempotencyKeyRequired", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/IdempotencyKeyRequiredEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "402": { "description": "InsufficientBalance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientBalanceEncoded" } } } }, "403": { "description": "EndpointNotPermitted | Forbidden", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EndpointNotPermittedEncoded" }, { "$ref": "#/components/schemas/ForbiddenEncoded" } ] } } } }, "409": { "description": "IdempotencyConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyConflictEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } }, "503": { "description": "ServiceUnavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableEncoded" } } } } }, "description": "Research keyword volume and difficulty, search rankings, backlinks, keyword and backlink gaps against competitors, ranking history, site crawls, single-page checks, and AI answer citations. Choose an action and supply keywords, a domain, or a page URL.\n\nEvery action returns normalized output with the last Run's id, provider and lifecycle status. List actions (keyword_ideas, serp, ranked_keywords, organic_competitors, backlinks, referring_domains, keyword_gap, backlink_gap, visibility_history, ai_citations, and keyword_overview with one row per keyword) expose output.items[] with fixed fields per row; overview actions (domain_overview, backlinks_overview, domain_rating, ai_visibility, page_audit, site_audit) expose fixed top-level fields. The Provider's native output is not repeated in output; it stays on the Run and is readable with GET /v1/runs/:id. A value the selected Provider does not report is null. Values are the answering Provider's own figures (volume, traffic and cpc are its estimates; compare them only within one Provider). Scores from a Provider's own model carry the Provider's name, such as ahrefs_domain_rating or semrush_keyword_difficulty, and are never converted between Providers. Money is always USD.\n\nRead result_status separately from status: success, no_result, error or pending. COMPLETED means the final Run settled with a Provider response; an empty but valid answer is no_result and keeps the action's shape (items is [], or every field is null). output is null on error or while pending.\n\ncharge_usd is the total of this response's runs, including charged empty results and failures, and is null until every listed Run settles. runs[] carries each Run's charge and charge_basis without bodies; a multi-Run total has charge_basis=null. GET /v1/runs/:id remains native with an individual charge.\n\nprovider=auto selects the first eligible Provider and tries the next only on PROVIDER_ERROR, TIMED_OUT, or a 503 at admission. No-result and in-flight Runs do not trigger fallback. A named Provider never falls back. Each admitted fallback is a separate Run; use task_id to find related Runs.\n\nFor QUEUED/RUNNING (HTTP 202, today only site_audit), poll the authenticated result_url on the API origin. That read returns the same normalized contract and total, creates no Runs and does not resume fallback. Reuse the same Idempotency-Key and execution parameters for an intentional retry.", "summary": "SEO research", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "anyOf": [ { "type": "string", "enum": [ "keyword_overview", "keyword_ideas", "serp", "domain_overview", "ranked_keywords", "organic_competitors", "backlinks_overview", "backlinks", "referring_domains", "domain_rating", "site_audit", "ai_visibility", "keyword_gap", "backlink_gap", "page_audit", "visibility_history", "ai_citations" ], "description": "Default: keyword_overview.\n\n- keyword_overview: supply one or more keywords.\n- keyword_ideas or serp: supply exactly one keyword in keywords.\n- site_audit: supply domain; limit is the number of pages to crawl (default 20, at most 100). The crawl runs asynchronously.\n- keyword_gap and backlink_gap: supply domain and one to four competitors.\n- page_audit: supply url (one page).\n- visibility_history: supply domain; limit is the number of months (default 12, at most 24).\n- All other actions: supply domain. organic_competitors finds domains ranking for the same keywords; ai_visibility: AI-answer visibility in the answering Provider's own metric (Ahrefs: citations of the domain's pages; DataForSEO: LLM mentions of the domain); ai_citations: pages most cited in AI answers that mention the domain, from any site.\n- keyword_gap rows differ by Provider: Semrush returns keywords any of the domains ranks for (union); DataForSEO returns keywords the competitor ranks for and you do not." }, { "type": "null" } ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "auto", "semrush", "serpstat", "dataforseo", "ahrefs", "serper" ], "description": "Default auto: select the first eligible Provider in Glasser's preference order. A named Provider must support the request and be allowed by your Key; it does not fall back to another Provider. Available values are listed below." }, { "type": "null" } ] }, "keywords": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 1, "maxLength": 200 }, "minItems": 1, "maxItems": 20 }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string", "minLength": 3, "maxLength": 253, "description": "A website domain such as stripe.com. A full URL is accepted and reduced to its host." }, { "type": "null" } ] }, "competitors": { "anyOf": [ { "type": "array", "items": { "type": "string", "minLength": 3, "maxLength": 253, "description": "A website domain such as stripe.com. A full URL is accepted and reduced to its host." }, "minItems": 1, "maxItems": 4, "description": "Competitor domains for keyword_gap and backlink_gap, one to four. Full URLs are reduced to their host." }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048, "description": "One page URL for page_audit, such as https://stripe.com/pricing." }, { "type": "null" } ] }, "country": { "anyOf": [ { "type": "string", "minLength": 2, "maxLength": 60, "description": "Country as a two-letter ISO code or a country name, e.g. us, gb, de, Germany. Default us. An unsupported country is refused with the supported list." }, { "type": "null" } ] }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100, "description": "Rows to return. Keep it small: the routed Endpoint's charge rule may read it. Each capability caps it further." }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string", "description": "Group related Runs, including automatic fallback, under one Task. Reuse a stable string and filter the Runs list by task to retrieve them." }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } }, {} ], "description": "Optional tracking fields, returned on the Run and available as filters. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name.\n\nInvalid entries are dropped whole, not truncated. The request continues, and the Run returns the fields that were stored." }, { "type": "null" } ] } }, "additionalProperties": false } } }, "required": true }, "x-mint": { "metadata": { "title": "SEO research", "description": "Research keyword volume and difficulty, search rankings, backlinks, site audits and AI-answer visibility across several Providers with one normalized output. Choose an action and supply keywords or a domain." }, "content": "Every action returns normalized `output`. The Provider's native output is not repeated there; it stays on the Run and is readable with [Get Run](/api-reference/runs/get). List actions expose `output.items[]` with fixed fields per row; overview actions expose fixed top-level fields. A value the selected Provider does not report is `null`; Glasser does not convert or fill in values. Money is always USD (`cpc_usd`, `organic_traffic_value_usd`).\n\n`volume`, `traffic` and `cpc_usd` are the answering Provider's own estimates. Compare them only within one Provider (`runs[].provider`), not across Providers.\n\nRead `result_status` separately from `status`: `success`, `no_result`, `error` or `pending`. An empty but valid answer is `no_result` and keeps the action's shape: `items` is `[]`, or every top-level field is `null`. `error` with `error.code` means the Provider output could not be delivered.\n\n`charge_usd` totals this response's `runs`, including charged empty results, and is null until all Runs settle. With `provider: auto`, fallback can create multiple Runs, each listed in `runs[]` with its own charge. For a pending crawl (`site_audit`, HTTP 202), follow the authenticated [result_url](/api-reference/solutions/gtm/seo_research/result). [Get Run](/api-reference/runs/get) remains native and reports an individual charge. See [Provider selection and charges](/api-reference/solutions/overview#how-provider-selection-works).\n\n## Output by action\n\nEvery field is present on every row; a value the Provider does not report is `null`. Fields follow the [field conventions](/api-reference/solutions/overview#field-conventions): money ends in `_usd`, timestamps end in `_at` (ISO 8601 UTC), and `domain` is a bare hostname without `www.` or a port.\n\nAuthority scores keep each Provider's own metric and name and are never converted: `ahrefs_domain_rating` (Ahrefs Domain Rating, 0–100, may have decimals), `semrush_authority_score` (Semrush Authority Score, 0–100), `dataforseo_rank` (DataForSEO rank, 0–1000) and `serpstat_domain_rank` (Serpstat Domain Rank, 0–100). Keyword difficulty is split the same way: `semrush_keyword_difficulty`, `serpstat_keyword_difficulty`, `dataforseo_keyword_difficulty` and `ahrefs_keyword_difficulty` are each 0–100 on the Provider's own model, so the same keyword can score very differently between them. `dataforseo_onpage_score` is DataForSEO's own page score. Only the field of the Provider that answered is filled; the others are `null`.\n\n`position` is the organic position: 1 is the first organic result, and SERP features such as ads or answer boxes are not counted.\n\n| action | `output` |\n| --- | --- |\n| `keyword_overview` | `items[]`: keyword, volume, cpc_usd, semrush_keyword_difficulty, serpstat_keyword_difficulty, dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, intent (one row per keyword) |\n| `keyword_ideas` | `items[]`: same row as `keyword_overview` |\n| `serp` | `items[]`: position, url, domain, title, snippet (organic results only) |\n| `domain_overview` | organic_keywords, organic_traffic, organic_traffic_value_usd, paid_keywords, paid_traffic |\n| `ranked_keywords` | `items[]`: keyword, position, url, volume, cpc_usd, traffic |\n| `organic_competitors` | `items[]`: domain, common_keywords, organic_keywords (the competitor's total), organic_traffic. The target domain and its subdomains are left out. |\n| `backlinks_overview` | backlinks, referring_domains, semrush_authority_score, dataforseo_rank, serpstat_domain_rank, dofollow_backlinks, nofollow_backlinks |\n| `backlinks` | `items[]`: source_url, target_url, anchor, source_ahrefs_domain_rating, source_semrush_authority_score, source_dataforseo_rank, dofollow, first_seen_at. One row per link from every Provider. |\n| `referring_domains` | `items[]`: domain, ahrefs_domain_rating, semrush_authority_score, dataforseo_rank, backlinks, dofollow_backlinks, first_seen_at |\n| `domain_rating` | ahrefs_domain_rating |\n| `site_audit` | dataforseo_task_id (input to DataForSEO's OnPage report Endpoints), crawl_progress, crawl_stop_reason (DataForSEO's vocabulary), pages_crawled, dataforseo_onpage_score, broken_links, non_indexable, duplicate_title, duplicate_description, duplicate_content |\n| `keyword_gap` | `items[]`: keyword, volume, cpc_usd, semrush_keyword_difficulty, dataforseo_keyword_difficulty, positions `{domain: position}` (`null` = not in the top 100), keyed by the domains you sent |\n| `backlink_gap` | `items[]`: domain, dataforseo_rank, backlinks_per_target `{competitor domain: count}` |\n| `page_audit` | url, status_code, title, description, canonical, dataforseo_onpage_score, internal_links, external_links |\n| `visibility_history` | `items[]`: month, organic_keywords, organic_traffic, organic_traffic_value_usd, paid_keywords, paid_traffic |\n| `ai_citations` | `items[]`: url, platform, mentions, ai_search_volume, is_target_domain. Pages most cited in AI answers that mention the domain, from any site. |\n| `ai_visibility` | ahrefs_ai_citations, ahrefs_ai_cited_pages, ahrefs_ai_citations_by_platform `{platform: citations}`, dataforseo_ai_mentions_by_platform `{platform: mentions}`, dataforseo_ai_search_volume_by_platform `{platform: AI search volume}` |\n\n`keyword_gap` rows differ by Provider: Semrush returns keywords any of the domains ranks for (a union), while DataForSEO returns keywords the competitor ranks for and you do not. `ai_visibility` reports two different metrics: Ahrefs counts citations of the domain's pages in AI answers, DataForSEO counts LLM mentions of the domain. Each Provider fills only its own fields, and there is no cross-Provider total. Semrush `first_seen_at` carries no time zone (Semrush does not state one), so it has no `Z` suffix.\n\n```json\n{\n \"action\": \"ranked_keywords\",\n \"provider\": \"dataforseo\",\n \"status\": \"COMPLETED\",\n \"result_status\": \"success\",\n \"output\": {\n \"items\": [\n { \"keyword\": \"zero interest business loan\", \"position\": 1, \"url\": \"https://stripe.com/resources/more/zero-interest-business-loans\", \"volume\": 1600, \"cpc_usd\": 14.54, \"traffic\": 486.4 }\n ]\n },\n \"charge_usd\": \"0.01236\",\n \"runs\": [{ \"provider\": \"dataforseo\", \"status\": \"COMPLETED\", \"charge_usd\": \"0.01236\" }],\n \"result_url\": \"/v1/solutions/gtm/seo_research/result?token=…\"\n}\n```", "href": "/api-reference/solutions/gtm/seo_research" } } }, "/v1/solutions/gtm/seo_research/result": { "get": { "tags": [ "Solutions" ], "operationId": "gtm-seo-research-result", "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "Opaque result context returned in result_url. Keep it unchanged and authenticate with a Key permitted to read every listed Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "SeoResearchResult", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeoResearchResult" } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Follow result_url from an SEO research call to read normalized output, business result_status and the total charge of the same Runs. HTTP 200 may still contain result_status=pending. This authenticated read creates no Runs, calls no Providers and does not resume fallback. GET /v1/runs/:id remains the native individual Run. The result context is signed, bound to the Workspace and checked against the current Key policy for every Run.", "summary": "Read an SEO research result", "x-mint": { "metadata": { "title": "Read an SEO research result", "description": "Read normalized output, delivery status, and total charges for an existing SEO research request. Follow the result_url returned by the call." }, "content": "Use `result_url` unchanged on the API origin and authenticate with a Key permitted to read every Run. The response uses the same fields as the initial Solution response. HTTP 200 can still carry `result_status: pending` while a crawl runs; keep polling until `status` is terminal. This read creates no Runs, calls no Providers and does not resume fallback.", "href": "/api-reference/solutions/gtm/seo_research/result" } } }, "/v1/solutions/gtm/social_research": { "post": { "tags": [ "Solutions" ], "operationId": "gtm-social-research", "parameters": [ { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "minLength": 1, "description": "Generate a unique value for each intended execution (a UUID is recommended). Retry with the same key and execution parameters to retrieve the original Run without a second charge. Changing execution parameters with the same key returns 409; changing task_id or metadata does not update the original Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SocialResearchResult" } ] } } } }, "202": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/SocialResearchResult" } ] } } } }, "400": { "description": "ValidationFailed | IdempotencyKeyRequired", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/IdempotencyKeyRequiredEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "402": { "description": "InsufficientBalance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientBalanceEncoded" } } } }, "403": { "description": "EndpointNotPermitted | Forbidden", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EndpointNotPermittedEncoded" }, { "$ref": "#/components/schemas/ForbiddenEncoded" } ] } } } }, "409": { "description": "IdempotencyConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyConflictEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } }, "503": { "description": "ServiceUnavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableEncoded" } } } } }, "description": "Public social media data on Reddit, X, YouTube, TikTok, Instagram and LinkedIn: search posts, read an account, its recent posts or one post, and find the same account on other platforms. Choose a platform and a mode and supply a query, handle or url.\n\nEvery mode returns normalized output shared by all six platforms, with the last Run's id, provider and lifecycle status: profile gives one account (platform, handle, name, url, bio, headline, website, followers, following, posts, verified), search and feed give output.items[] of posts (id, url, title, text, author, author_url, published_at, likes, comments, shares, views), post gives one post with the same fields, find gives output.profiles[] (platform, url, handle, scrapecreators_confidence, followers; for Reddit the matching subreddits) plus pdl_likelihood. The Provider's native output is not repeated in output; it stays on the Run and is readable with GET /v1/runs/:id. A value a platform or Provider does not report is null.\n\nRead result_status separately from status: success, no_result, error or pending. An empty but valid answer is no_result and keeps the mode's shape (items or profiles is [], or every field is null). charge_usd is the total of this response's runs and is null until every listed Run settles. provider=auto selects the first eligible Provider and tries the next only on PROVIDER_ERROR, TIMED_OUT, or a 503 at admission; a named Provider never falls back. For QUEUED/RUNNING (HTTP 202, the Apify routes), poll the authenticated result_url on the API origin. Reuse the same Idempotency-Key and execution parameters for an intentional retry.", "summary": "Social research", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "platform": { "type": "string", "enum": [ "reddit", "x", "youtube", "tiktok", "instagram", "linkedin" ] }, "mode": { "anyOf": [ { "type": "string", "enum": [ "search", "profile", "feed", "post", "find" ], "description": "Default: search. Every platform supports each mode.\n\n- search: posts matching query.\n- profile: account details from handle (Reddit: subreddit). For LinkedIn, supply a person or company url.\n- feed: recent posts or videos from handle. For LinkedIn, supply a company url.\n- post: one post or video from url.\n- find: other social profiles from handle. For LinkedIn, supply a person's profile url; for Reddit, supply query to find subreddits." }, { "type": "null" } ] }, "provider": { "anyOf": [ { "type": "string", "enum": [ "auto", "scrapecreators", "apify", "tikhub", "pdl" ], "description": "Default auto: select the first eligible Provider in Glasser's preference order. A named Provider must support the request and be allowed by your Key; it does not fall back to another Provider. Available values are listed below." }, { "type": "null" } ] }, "query": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 500 }, { "type": "null" } ] }, "handle": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100, "description": "A username without @, or a subreddit name without r/." }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 2048 }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } }, {} ], "description": "Optional tracking fields, returned on the Run and available as filters. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name.\n\nInvalid entries are dropped whole, not truncated. The request continues, and the Run returns the fields that were stored." }, { "type": "null" } ] } }, "required": [ "platform" ], "additionalProperties": false } } }, "required": true }, "x-mint": { "metadata": { "title": "Social research", "description": "Public social media data on Reddit, X, YouTube, TikTok, Instagram and LinkedIn, with one normalized output per mode shared by every platform." }, "content": "Every mode returns normalized `output` shared by all six platforms. The Provider's native output is not repeated there; it stays on the Run and is readable with [Get Run](/api-reference/runs/get). A value a platform or Provider does not report is `null`.\n\nRead `result_status` separately from `status`: `success`, `no_result`, `error` or `pending`. An empty but valid answer is `no_result` and keeps the mode's shape: `items` or `profiles` is `[]`, or every field is `null`. `charge_usd` totals this response's `runs`. For a pending Apify route (HTTP 202), follow the authenticated [result_url](/api-reference/solutions/gtm/social_research/result). See [Provider selection and charges](/api-reference/solutions/overview#how-provider-selection-works).\n\n## Output by mode\n\nFields follow the [field conventions](/api-reference/solutions/overview#field-conventions).\n\n| mode | `output` |\n| --- | --- |\n| `profile` | platform, handle, name, url, bio, headline, website, followers, following, posts, verified |\n| `search` | `items[]`: id, url, title, text, author, author_url, published_at, likes, comments, shares, views |\n| `feed` | `items[]`: the same post fields |\n| `post` | id, url, title, text, author, author_url, published_at, likes, comments, shares, views |\n| `find` | `profiles[]`: platform, url, handle, scrapecreators_confidence, followers (for Reddit: matching subreddits); top-level pdl_likelihood |\n\n- `published_at` is ISO 8601 UTC, or `null` when the Provider gives no exact time (YouTube search results).\n- `title` is the Reddit or YouTube title. `text` is the body only (Reddit self-text, YouTube description, the tweet, caption or post text), and is `null` when there is none.\n- `bio` is the free-text description (LinkedIn: the About section). `headline` is the LinkedIn job-title line. `website` is the account's own site: the LinkedIn company website or the expanded X profile link.\n- `likes` is Reddit's net score (can be negative), X favorites, TikTok diggs, or likes and reactions elsewhere. `shares` is X retweets, TikTok share-sheet sends, or LinkedIn reposts. `views` is X impressions, TikTok plays, or YouTube and Instagram video views.\n- In `find`, `platform` is the lower-case network name (`twitter` becomes `x`), and `handle` is usable as the social_research `handle`. `scrapecreators_confidence` is ScrapeCreators' 0–1 score per profile. `pdl_likelihood` is People Data Labs' 1–10 match score for the whole person, filled only on `linkedin.find`.\n- LinkedIn `id` is the bare activity id, without the `urn:li:activity:` prefix.\n\n```json\n{\n \"action\": \"x.feed\",\n \"provider\": \"scrapecreators\",\n \"status\": \"COMPLETED\",\n \"result_status\": \"success\",\n \"output\": {\n \"items\": [\n { \"id\": \"2110166802315804689\", \"url\": \"https://x.com/stripe/status/2110166802315804689\", \"title\": null, \"text\": \"You can now use Underdog…\", \"author\": \"stripe\", \"author_url\": \"https://x.com/stripe\", \"published_at\": \"2026-10-14T00:32:25Z\", \"likes\": 55, \"comments\": 21, \"shares\": 6, \"views\": 8447 }\n ]\n },\n \"charge_usd\": \"0.00188\",\n \"runs\": [{ \"provider\": \"scrapecreators\", \"status\": \"COMPLETED\", \"charge_usd\": \"0.00188\" }],\n \"result_url\": \"/v1/solutions/gtm/social_research/result?token=…\"\n}\n```", "href": "/api-reference/solutions/gtm/social_research" } } }, "/v1/solutions/gtm/social_research/result": { "get": { "tags": [ "Solutions" ], "operationId": "gtm-social-research-result", "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "Opaque result context returned in result_url. Keep it unchanged and authenticate with a Key permitted to read every listed Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "SocialResearchResult", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SocialResearchResult" } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Follow result_url from a social research call to read normalized output, business result_status and the total charge of the same Runs. HTTP 200 may still contain result_status=pending. This authenticated read creates no Runs, calls no Providers and does not resume fallback. GET /v1/runs/:id remains the native individual Run. The result context is signed, bound to the Workspace and checked against the current Key policy for every Run.", "summary": "Read a social research result", "x-mint": { "metadata": { "title": "Read a social research result", "description": "Read normalized output, delivery status, and total charges for an existing social research request. Follow the result_url returned by the call." }, "content": "Use `result_url` unchanged on the API origin and authenticate with a Key permitted to read every Run. The response uses the same fields as the initial Solution response. HTTP 200 can still carry `result_status: pending` while an Apify route runs; keep polling until `status` is terminal. This read creates no Runs, calls no Providers and does not resume fallback.", "href": "/api-reference/solutions/gtm/social_research/result" } } }, "/v1/solutions/gtm/market_data": { "post": { "tags": [ "Solutions" ], "operationId": "gtm-market-data", "parameters": [ { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "minLength": 1, "description": "Generate a unique value for each intended execution (a UUID is recommended). Retry with the same key and execution parameters to retrieve the original Run without a second charge. Changing execution parameters with the same key returns 409; changing task_id or metadata does not update the original Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MarketDataResult" } ] } } } }, "202": { "description": "Success", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/MarketDataResult" } ] } } } }, "400": { "description": "ValidationFailed | IdempotencyKeyRequired", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/IdempotencyKeyRequiredEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "402": { "description": "InsufficientBalance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientBalanceEncoded" } } } }, "403": { "description": "EndpointNotPermitted | Forbidden", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EndpointNotPermittedEncoded" }, { "$ref": "#/components/schemas/ForbiddenEncoded" } ] } } } }, "409": { "description": "IdempotencyConflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyConflictEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } }, "503": { "description": "ServiceUnavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableEncoded" } } } } }, "description": "US property values, rent estimates, property records, sale and rental listings, ZIP-level market statistics, and stock quotes. Choose an action and supply an address, a city plus state, a ZIP, or a ticker symbol.\n\nEvery action returns normalized output with the last Run's id, provider and lifecycle status: property_value, property_rent, market_stats and stock_quote give fixed top-level fields; property_search, listings_sale and listings_rental give output.items[] with fixed fields per row. The Provider's native output is not repeated in output; it stays on the Run and is readable with GET /v1/runs/:id. A value the Provider does not report is null; property money is USD, a stock quote carries its currency.\n\nRead result_status separately from status: success, no_result, error or pending. charge_usd is the total of this response's runs and is null until every listed Run settles; runs[] carries each Run's charge. A named Provider never falls back. For QUEUED/RUNNING (HTTP 202), poll the authenticated result_url on the API origin. Reuse the same Idempotency-Key and execution parameters for an intentional retry.", "summary": "Market data", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "action": { "type": "string", "enum": [ "property_value", "property_rent", "property_search", "listings_sale", "listings_rental", "market_stats", "stock_quote" ], "description": "Choose the data to retrieve:\n\n- property_value or property_rent: supply address.\n- property_search, listings_sale, or listings_rental: supply address, city plus state, or zip.\n- market_stats: supply zip.\n- stock_quote: supply symbol." }, "provider": { "anyOf": [ { "type": "string", "enum": [ "auto", "rentcast", "serpapi" ], "description": "Default auto: select the first eligible Provider in Glasser's preference order. A named Provider must support the request and be allowed by your Key; it does not fall back to another Provider. Available values are listed below." }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 300 }, { "type": "null" } ] }, "city": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 100 }, { "type": "null" } ] }, "state": { "anyOf": [ { "type": "string", "pattern": "^[A-Za-z]{2}$" }, { "type": "null" } ] }, "zip": { "anyOf": [ { "type": "string", "pattern": "^\\d{5}$" }, { "type": "null" } ] }, "symbol": { "anyOf": [ { "type": "string", "minLength": 1, "maxLength": 40 }, { "type": "null" } ] }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 100, "description": "Rows to return. Keep it small: the routed Endpoint's charge rule may read it. Each capability caps it further." }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string", "description": "Group related Runs, including automatic fallback, under one Task. Reuse a stable string and filter the Runs list by task to retrieve them." }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } }, {} ], "description": "Optional tracking fields, returned on the Run and available as filters. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name.\n\nInvalid entries are dropped whole, not truncated. The request continues, and the Run returns the fields that were stored." }, { "type": "null" } ] } }, "required": [ "action" ], "additionalProperties": false } } }, "required": true }, "x-mint": { "metadata": { "title": "Market data", "description": "US property values, rent estimates, property records, listings, ZIP-level market statistics and stock quotes, with one normalized output." }, "content": "Every action returns normalized `output`. The Provider's native output is not repeated there; it stays on the Run and is readable with [Get Run](/api-reference/runs/get). `property_value`, `property_rent`, `market_stats` and `stock_quote` expose fixed top-level fields; `property_search`, `listings_sale` and `listings_rental` expose `output.items[]`. A value the Provider does not report is `null`. Property money is USD; a stock quote carries its `currency`.\n\nRead `result_status` separately from `status`: `success`, `no_result`, `error` or `pending`. An empty but valid answer, such as an address without an estimate, is `no_result` and keeps the action's shape: every field is `null`, or `items` is `[]`. `charge_usd` totals this response's `runs`. See [Provider selection and charges](/api-reference/solutions/overview#how-provider-selection-works).\n\n## Output by action\n\nProperty fields are `address`, `property_type`, `bedrooms`, `bathrooms`, `living_area_sqft`, `lot_size_sqft`, `year_built`, `latitude`, `longitude`. Listing fields are `listing_id`, the property fields, `status`, `listing_type`, `listed_date`, `days_on_market`, `hoa_fee_usd` (monthly HOA fee), `mls_name`, `mls_number`, `agent` and `office`. `agent` and `office` are `{name, phone, email, website}`, or `null` when the Provider reports none.\n\n| action | `output` |\n| --- | --- |\n| `property_value` | property fields plus estimated_value_usd, value_low_usd, value_high_usd, comparables_count |\n| `property_rent` | property fields plus estimated_rent_usd (monthly), rent_low_usd, rent_high_usd, comparables_count |\n| `property_search` | `items[]`: property_id, property fields, last_sale_price_usd, last_sale_date, owner_names[], owner_type, owner_mailing_address, owner_occupied |\n| `listings_sale` | `items[]`: listing fields plus price_usd (asking price) |\n| `listings_rental` | `items[]`: listing fields plus monthly_rent_usd |\n| `market_stats` | zip, updated_at, sale `{average_price_usd, median_price_usd, average_price_per_sqft_usd, median_price_per_sqft_usd, average_days_on_market, median_days_on_market, total_listings, new_listings}`, rental `{average_rent_usd, median_rent_usd, average_rent_per_sqft_usd, median_rent_per_sqft_usd, average_days_on_market, median_days_on_market, total_listings, new_listings}` |\n| `stock_quote` | symbol, name, exchange, currency, price, change, change_percent, extended_hours_session, extended_hours_price, extended_hours_change, extended_hours_change_percent, as_of_text |\n\n- `comparables_count` is the number of comparable sales or rentals behind the estimate.\n- `last_sale_date` and `listed_date` are `YYYY-MM-DD`; `updated_at` is ISO 8601 UTC, when RentCast last refreshed the aggregate.\n- The `rental` side of `market_stats`, `monthly_rent_usd` and `estimated_rent_usd` are monthly rents.\n- `price` is the regular-session last price in `currency`; Google Finance quotes may be delayed. `change` is the absolute move in `currency` and `change_percent` is in percent points (1.5 = 1.5%), both against the previous regular close.\n- `extended_hours_session` is the session label as shown (Pre-market or After hours) and is `null` during regular hours. The `extended_hours_*` values compare the extended-hours quote with the regular-session price, in the same units.\n- `as_of_text` is the Google Finance page timestamp exactly as shown. It is not ISO and not the time of `price`.\n\n```json\n{\n \"action\": \"property_value\",\n \"provider\": \"rentcast\",\n \"status\": \"COMPLETED\",\n \"result_status\": \"success\",\n \"output\": {\n \"address\": \"5500 Grand Lake Dr, San Antonio, TX 78244\", \"property_type\": \"Single Family\",\n \"bedrooms\": 3, \"bathrooms\": 2, \"living_area_sqft\": 1878, \"lot_size_sqft\": 8843, \"year_built\": 1973,\n \"latitude\": 29.476011, \"longitude\": -98.351454,\n \"estimated_value_usd\": 235000, \"value_low_usd\": 203000, \"value_high_usd\": 266000, \"comparables_count\": 15\n },\n \"charge_usd\": \"0.0814\",\n \"runs\": [{ \"provider\": \"rentcast\", \"status\": \"COMPLETED\", \"charge_usd\": \"0.0814\" }],\n \"result_url\": \"/v1/solutions/gtm/market_data/result?token=…\"\n}\n```", "href": "/api-reference/solutions/gtm/market_data" } } }, "/v1/solutions/gtm/market_data/result": { "get": { "tags": [ "Solutions" ], "operationId": "gtm-market-data-result", "parameters": [ { "name": "token", "in": "query", "schema": { "type": "string", "minLength": 1, "maxLength": 16384, "description": "Opaque result context returned in result_url. Keep it unchanged and authenticate with a Key permitted to read every listed Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "MarketDataResult", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketDataResult" } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Follow result_url from a market data call to read normalized output, business result_status and the total charge of the same Runs. HTTP 200 may still contain result_status=pending. This authenticated read creates no Runs, calls no Providers and does not resume fallback. GET /v1/runs/:id remains the native individual Run. The result context is signed, bound to the Workspace and checked against the current Key policy for every Run.", "summary": "Read a market data result", "x-mint": { "metadata": { "title": "Read a market data result", "description": "Read normalized output, delivery status, and total charges for an existing market data request. Follow the result_url returned by the call." }, "content": "Use `result_url` unchanged on the API origin and authenticate with a Key permitted to read every Run. The response uses the same fields as the initial Solution response. HTTP 200 can still carry `result_status: pending`; keep polling until `status` is terminal. This read creates no Runs, calls no Providers and does not resume fallback.", "href": "/api-reference/solutions/gtm/market_data/result" } } }, "/v1/endpoints/search": { "post": { "tags": [ "Endpoints" ], "operationId": "endpoints-search", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "provider_label": { "type": "string", "description": "The Provider's brand name, for display: \"People Data Labs\" for provider \"pdl\". Identity stays with `provider` — that is the value run and inspect take, and this one is never sent back." }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0, "description": "Supported Endpoint version. Compatible updates keep this version." }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "price": { "type": "object", "properties": { "rule": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "flat" ] }, "amount_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "type", "amount_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "per_result" ] }, "per_result_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "partial_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "type", "per_result_usd", "cap_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "per_token" ] }, "per_million_input_tokens_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "type", "per_million_input_tokens_usd", "cap_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base_plus_per_result" ] }, "base_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "included_results": { "type": "integer", "minimum": 0 }, "per_extra_result_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "unit": { "type": "string" } }, "required": [ "type", "base_usd", "included_results", "per_extra_result_usd", "cap_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "metered" ] }, "base_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "type", "base_usd", "cap_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "per_event" ] }, "events": { "type": "object", "additionalProperties": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "title": { "type": "string" } }, "required": [ "usd", "title" ], "additionalProperties": false } }, "base_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "type", "events", "base_usd", "cap_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "allOf": [ { "type": "object", "additionalProperties": {} } ] } ] }, "display": { "type": "object", "properties": { "amount_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "unit": { "type": "string" }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "amount_usd", "unit" ], "additionalProperties": false }, "charges": { "type": "object", "properties": { "NO_RESULT": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "PROVIDER_ERROR": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "TIMED_OUT": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "INTERNAL": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ], "additionalProperties": false } }, "required": [ "rule", "display", "charges" ], "additionalProperties": false, "description": "Current Price and charging rules. Price can change without an Endpoint version change. New Runs use the Price at admission; accepted Runs keep that Price." }, "run_mode": { "type": "string", "enum": [ "sync", "async" ] }, "timeout_ms": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "description": "For sync Endpoints, the maximum time in milliseconds from a Run request to its terminal response. Set your HTTP client timeout above this value." }, { "type": "null" } ] }, "score": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Cosine similarity between the query and this endpoint's searchable text, in [-1, 1]; null when semantic scoring did not run. A similarity signal for comparing rows, not a verdict: ranking fuses two arms, and neither a low score nor the end of the results shows that a capability is absent." } }, "required": [ "provider", "provider_label", "endpoint", "endpoint_version", "name", "description", "tags", "price", "run_mode", "score" ], "additionalProperties": false }, "description": "Endpoint summaries ranked by relevance and filtered by your Key's Policy. Price does not affect ranking." }, "client": { "type": "object", "properties": { "client_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum_version": { "type": "string" }, "latest_version": { "type": "string" }, "upgrade_command": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "client_version", "minimum_version", "latest_version", "upgrade_command", "reason" ], "additionalProperties": false }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Pass this value as cursor to get the next page. Null means there are no more pages." }, "total": { "type": "integer", "minimum": 0, "description": "Total number of ranked candidates across all pages." }, "task_id": { "type": "string", "description": "The task this search was recorded against — the one you sent, or a newly minted one if you sent none. Pass it back on every later search, inspect and run for the same piece of work." } }, "required": [ "data", "next_cursor", "total", "task_id" ], "additionalProperties": false } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Find runnable Endpoints by keyword; this returns Endpoint candidates, not business data. Results are ranked by relevance, filtered by your Key's Policy, and include Provider, Endpoint version, Price, and run mode. Compare candidates and Inspect before running.\n\nUse next_cursor for more results. Low scores or the last page do not prove that a capability is absent; try different keywords. Reuse the returned task_id for later calls on the same task.", "summary": "Search runnable endpoints", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "anyOf": [ { "type": "string", "description": "Keywords that describe the data you need. Omit or leave empty to browse all Endpoints allowed by your Key's Policy." }, { "type": "null" } ] }, "limit": { "anyOf": [ { "type": "integer", "minimum": 1, "maximum": 20, "description": "Maximum results per page. Default: 5; maximum: 20." }, { "type": "null" } ] }, "cursor": { "anyOf": [ { "type": "string", "description": "The next_cursor from the previous response. Use the same query; a cursor from a different query returns 400." }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string", "description": "The task this search belongs to. A search without a task_id starts a new task. The response returns its task_id. Send it on every later search, inspect and run of the same piece of work. Any stable string is accepted." }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } }, {} ], "description": "Optional tracking fields, returned on the Run and available as filters. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name.\n\nInvalid entries are dropped whole, not truncated. The request continues, and the Run returns the fields that were stored." }, { "type": "null" } ] }, "use_case": { "type": "string", "minLength": 1, "description": "Required on every search. The use case behind this search: what the user asked for, in their own words, with the subject in it — the company, domain, ticker, place or topic. Shorten a long request rather than rewriting it." } }, "required": [ "use_case" ], "additionalProperties": false } } }, "required": true }, "x-mint": { "metadata": { "title": "Search runnable endpoints", "description": "Find Endpoints for the data you need and compare Providers and Prices. Search returns ways to retrieve data; it does not retrieve the data itself." }, "content": "Choose a candidate, then [Inspect it](/api-reference/endpoints/inspect) before running it. If results do not fit, try different keywords; low scores or the last page do not prove a capability is unavailable.", "href": "/api-reference/endpoints/search" } } }, "/v1/endpoints/inspect": { "post": { "tags": [ "Endpoints" ], "operationId": "endpoints-inspect", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "provider_label": { "type": "string", "description": "The Provider's brand name, for display: \"People Data Labs\" for provider \"pdl\". Identity stays with `provider` — that is the value run and inspect take, and this one is never sent back." }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0, "description": "Supported Endpoint version. Compatible updates keep this version." }, "name": { "type": "string" }, "description": { "type": "string" }, "tags": { "type": "array", "items": { "type": "string" } }, "price": { "type": "object", "properties": { "rule": { "anyOf": [ { "type": "object", "properties": { "type": { "type": "string", "enum": [ "flat" ] }, "amount_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "type", "amount_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "per_result" ] }, "per_result_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "partial_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "type", "per_result_usd", "cap_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "per_token" ] }, "per_million_input_tokens_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "type", "per_million_input_tokens_usd", "cap_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "base_plus_per_result" ] }, "base_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "included_results": { "type": "integer", "minimum": 0 }, "per_extra_result_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "unit": { "type": "string" } }, "required": [ "type", "base_usd", "included_results", "per_extra_result_usd", "cap_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "metered" ] }, "base_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "type", "base_usd", "cap_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string", "enum": [ "per_event" ] }, "events": { "type": "object", "additionalProperties": { "type": "object", "properties": { "usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "title": { "type": "string" } }, "required": [ "usd", "title" ], "additionalProperties": false } }, "base_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "type", "events", "base_usd", "cap_usd" ], "additionalProperties": false }, { "type": "object", "properties": { "type": { "type": "string" } }, "required": [ "type" ], "allOf": [ { "type": "object", "additionalProperties": {} } ] } ] }, "display": { "type": "object", "properties": { "amount_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "unit": { "type": "string" }, "cap_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "amount_usd", "unit" ], "additionalProperties": false }, "charges": { "type": "object", "properties": { "NO_RESULT": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "PROVIDER_ERROR": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "TIMED_OUT": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, "INTERNAL": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." } }, "required": [ "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ], "additionalProperties": false } }, "required": [ "rule", "display", "charges" ], "additionalProperties": false, "description": "Current Price and charging rules. Price can change without an Endpoint version change. New Runs use the Price at admission; accepted Runs keep that Price." }, "run_mode": { "type": "string", "enum": [ "sync", "async" ] }, "timeout_ms": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "description": "For sync Endpoints, the maximum time in milliseconds from a Run request to its terminal response. Set your HTTP client timeout above this value." }, { "type": "null" } ] }, "client": { "type": "object", "properties": { "client_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum_version": { "type": "string" }, "latest_version": { "type": "string" }, "upgrade_command": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "client_version", "minimum_version", "latest_version", "upgrade_command", "reason" ], "additionalProperties": false }, "method": { "type": "string", "enum": [ "GET", "POST", "PUT", "PATCH", "DELETE", "HEAD" ] }, "input_schema": { "type": "object", "description": "Provider-native JSON Schema for Run input." }, "output_schema": { "anyOf": [ { "type": "object" }, { "type": "null" } ], "description": "JSON Schema for successful output. Null when no reliable schema is available; sample responses do not define a schema." }, "output_schema_source": { "anyOf": [ { "type": "string", "enum": [ "provider", "glasser" ] }, { "type": "null" } ], "description": "Who defines the output schema: the Provider or Glasser. Null when output_schema is null." }, "sample_input": { "type": "object", "description": "Example input. Adjust it to your request and validate it against input_schema." }, "doc_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Link to the Provider's documentation, when available." } }, "required": [ "provider", "provider_label", "endpoint", "endpoint_version", "name", "description", "tags", "price", "run_mode", "method", "input_schema", "output_schema", "output_schema_source", "sample_input", "doc_url" ], "additionalProperties": false } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEncoded" } } } }, "409": { "description": "EndpointVersionMismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EndpointVersionMismatchEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Get an Endpoint's input schema, available output schema, Price, example input, version, run mode, and timeout. Inspect before the first Run and use the returned input_schema and endpoint_version.\n\nAn output_schema of null means no reliable schema is available. Endpoint versions do not lock Price: new Runs use the Price at admission. For sync Endpoints, set your HTTP client timeout above timeout_ms.", "summary": "Inspect an Endpoint", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "description": "Select a supported Endpoint version, including an older one, or omit for the default. Unavailable or retired versions return 409." }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string", "description": "The task this inspection belongs to, from a catalog search response. Any stable string is accepted." }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } }, {} ], "description": "Optional tracking fields, returned on the Run and available as filters. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name.\n\nInvalid entries are dropped whole, not truncated. The request continues, and the Run returns the fields that were stored." }, { "type": "null" } ] } }, "required": [ "provider", "endpoint" ], "additionalProperties": false } } }, "required": true }, "x-mint": { "metadata": { "title": "Inspect an Endpoint", "description": "Get an Endpoint's schemas, current Price, and example input. Use these details to prepare a Run." }, "content": "Use `input_schema` to prepare your request and review the Price before running it. Save `endpoint_version` for the Run; it does not lock the Price. For sync Endpoints, set your client timeout above `timeout_ms`.", "href": "/api-reference/endpoints/inspect" } } }, "/v1/runs": { "post": { "tags": [ "Runs" ], "operationId": "runs-create", "parameters": [ { "name": "idempotency-key", "in": "header", "schema": { "type": "string", "minLength": 1, "description": "Generate a unique value for each intended execution (a UUID is recommended). Retry with the same key and execution parameters to retrieve the original Run without a second charge. Changing execution parameters with the same key returns 409; changing task_id or metadata does not update the original Run." }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "a terminal run: COMPLETED, FAILED or STOPPED", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object" }, "output": {}, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." }, "error": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when status is COMPLETED.\n\n- For 2xx responses, output contains Provider-native JSON (any shape), or null for an empty body.\n- For non-2xx responses, error contains the Provider's error body and output is null.\n\nSensitive fields are removed from both bodies." }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Final charge as an exact USD decimal string. Null while QUEUED or RUNNING. A FAILED Run can have a non-zero charge under the Endpoint's Price." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Price clause used to calculate the charge. Null before settlement or when no Provider attempt was made." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata" ], "additionalProperties": false } } } }, "202": { "description": "an in-flight run: QUEUED or RUNNING", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object" }, "output": {}, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." }, "error": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when status is COMPLETED.\n\n- For 2xx responses, output contains Provider-native JSON (any shape), or null for an empty body.\n- For non-2xx responses, error contains the Provider's error body and output is null.\n\nSensitive fields are removed from both bodies." }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Final charge as an exact USD decimal string. Null while QUEUED or RUNNING. A FAILED Run can have a non-zero charge under the Endpoint's Price." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Price clause used to calculate the charge. Null before settlement or when no Provider attempt was made." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata" ], "additionalProperties": false } } } }, "400": { "description": "ValidationFailed | IdempotencyKeyRequired", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/IdempotencyKeyRequiredEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "402": { "description": "InsufficientBalance", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InsufficientBalanceEncoded" } } } }, "403": { "description": "EndpointNotPermitted | Forbidden", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EndpointNotPermittedEncoded" }, { "$ref": "#/components/schemas/ForbiddenEncoded" } ] } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEncoded" } } } }, "409": { "description": "IdempotencyConflict | EndpointVersionMismatch", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/IdempotencyConflictEncoded" }, { "$ref": "#/components/schemas/EndpointVersionMismatchEncoded" } ] } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } }, "503": { "description": "ServiceUnavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceUnavailableEncoded" } } } } }, "description": "Execute an Endpoint with Provider-native input prepared from Inspect. Glasser checks your Key's Policy and reserves the maximum charge before creating a Run. A refusal creates no Run and no charge. Reuse the same Idempotency-Key and execution parameters to retry without a second execution.\n\n- **200:** the Run has finished. Check its status, Provider response, and charge.\n- **202:** an async Run is still in progress. Use Get Run to read its result. Sync Endpoints always return a finished Run within their published timeout_ms.\n\nCOMPLETED can include a Provider error; check provider_response. Status and charge are independent: a FAILED Run can have a charge.", "summary": "Run an Endpoint", "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "input": { "type": "object", "description": "Provider-native input. Build it from the input_schema returned by Inspect." }, "endpoint_version": { "anyOf": [ { "type": "integer", "exclusiveMinimum": 0, "description": "Select a supported version, or omit for the default. Compatible updates keep the version; unavailable or retired versions return 409. A version does not lock Price: new Runs use the Price at admission, and accepted Runs keep it through settlement." }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string", "description": "The task this run belongs to, from a catalog search response. Grouping only: it never affects routing, price or idempotency." }, { "type": "null" } ] }, "metadata": { "anyOf": [ { "anyOf": [ { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" } }, {} ], "description": "Optional tracking fields, returned on the Run and available as filters. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name.\n\nInvalid entries are dropped whole, not truncated. The request continues, and the Run returns the fields that were stored." }, { "type": "null" } ] } }, "required": [ "provider", "endpoint" ], "additionalProperties": false } } }, "required": true }, "x-mint": { "metadata": { "title": "Create a Run", "description": "Execute an Endpoint with the input prepared from Inspect. Glasser checks your Key’s Policy and reserves funds before creating a Run." }, "content": "- **200:** the Run has finished. Check its status, Provider response, and charge.\n- **202:** an async Run is still in progress. Use [Get a Run](/api-reference/runs/get) to check its result.\n\nA finished Run can contain a Provider error. Use the same `Idempotency-Key` and execution parameters when retrying.", "href": "/api-reference/runs/create" } }, "get": { "tags": [ "Runs" ], "operationId": "runs-list", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "string", "pattern": "^[+-]?\\d*\\.?\\d+(?:[Ee][+-]?\\d+)?$" }, "required": false }, { "name": "cursor", "in": "query", "schema": { "anyOf": [ { "type": "string", "description": "Pass next_cursor from the previous response to read the next page." }, { "type": "null" } ] }, "required": false }, { "name": "status", "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ] }, { "type": "null" } ] }, "required": false }, { "name": "provider", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "required": false }, { "name": "endpoint", "in": "query", "schema": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "required": false }, { "name": "task", "in": "query", "schema": { "anyOf": [ { "type": "string", "description": "Return only runs recorded against this task. Exact match." }, { "type": "null" } ] }, "required": false }, { "name": "metadata", "in": "query", "schema": { "anyOf": [ { "type": "string", "description": "Return only runs whose metadata contains every key-value pair of this JSON object, for example {\"user_id\":\"user_123\"}. Exact match.", "contentMediaType": "application/json" }, { "type": "null" } ] }, "required": false } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "output": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ] }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Final charge as an exact USD decimal string. Null while QUEUED or RUNNING. A FAILED Run can have a non-zero charge under the Endpoint's Price." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Price clause used to calculate the charge. Null before settlement or when no Provider attempt was made." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata" ], "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page. Null when there are no more entries." }, "client": { "type": "object", "properties": { "client_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum_version": { "type": "string" }, "latest_version": { "type": "string" }, "upgrade_command": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "client_version", "minimum_version", "latest_version", "upgrade_command", "reason" ], "additionalProperties": false } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Review Runs, newest first. Filter by status, Provider, Endpoint, Task, or metadata, and use next_cursor to read the next page. Only Runs permitted by your Key's Policy are visible.\n\nEach row is a summary: input and output contain {\"omitted\": true}, and Provider error bodies are excluded. Use Get a Run for the full input, output, and error details.", "summary": "List Runs", "x-mint": { "metadata": { "title": "List Runs", "description": "Review your Runs, newest first. Filter by status, Provider, Endpoint, Task, or metadata." }, "content": "Each row is a summary. Use [Get a Run](/api-reference/runs/get) for the full input, output, and Provider error details.", "href": "/api-reference/runs/list" } } }, "/v1/runs/{runId}": { "get": { "tags": [ "Runs" ], "operationId": "runs-get", "parameters": [ { "name": "runId", "in": "path", "schema": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$", "format": "uuid" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object" }, "output": {}, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." }, "error": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when status is COMPLETED.\n\n- For 2xx responses, output contains Provider-native JSON (any shape), or null for an empty body.\n- For non-2xx responses, error contains the Provider's error body and output is null.\n\nSensitive fields are removed from both bodies." }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Final charge as an exact USD decimal string. Null while QUEUED or RUNNING. A FAILED Run can have a non-zero charge under the Endpoint's Price." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Price clause used to calculate the charge. Null before settlement or when no Provider attempt was made." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata" ], "additionalProperties": false } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedEncoded" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Read a Run's current status, result, and charge. Use this to check an unfinished Run or retrieve a previous result.\n\nCheck status and provider_response before using output. A COMPLETED Run can include a Provider error; a FAILED Run can still have a charge.", "summary": "Get a Run", "x-mint": { "metadata": { "title": "Get a Run", "description": "Read a Run's current status, result, and charge. Use this to check an unfinished Run or retrieve a previous result." }, "content": "Check `status` and `provider_response` before using `output`. A `COMPLETED` Run can include a Provider error; a `FAILED` Run can still have a charge.", "href": "/api-reference/runs/get" } } }, "/v1/runs/{runId}/stop": { "post": { "tags": [ "Runs" ], "operationId": "runs-stop", "parameters": [ { "name": "runId", "in": "path", "schema": { "type": "string", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|[fF]{8}-[fF]{4}-[fF]{4}-[fF]{4}-[fF]{12})$", "format": "uuid" }, "required": true } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object" }, "output": {}, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." }, "error": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when status is COMPLETED.\n\n- For 2xx responses, output contains Provider-native JSON (any shape), or null for an empty body.\n- For non-2xx responses, error contains the Provider's error body and output is null.\n\nSensitive fields are removed from both bodies." }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Final charge as an exact USD decimal string. Null while QUEUED or RUNNING. A FAILED Run can have a non-zero charge under the Endpoint's Price." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Price clause used to calculate the charge. Null before settlement or when no Provider attempt was made." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata" ], "additionalProperties": false } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedEncoded" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "404": { "description": "NotFound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundEncoded" } } } }, "409": { "description": "Conflict", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ConflictEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Request a stop and check the returned status. Accepting the request does not guarantee that execution stopped.\n\n- **Before dispatch:** the Run becomes STOPPED with no charge. An expired sync deadline takes precedence and produces FAILED with TIMED_OUT.\n- **After dispatch:** the Run continues; stop_requested_at records your request. Its Price determines the final charge.\n- **Already finished:** returns 409.", "summary": "Stop a Run", "x-mint": { "metadata": { "title": "Stop a Run", "description": "Request a stop for an unfinished Run. Whether it can stop depends on whether dispatch has started." }, "content": "- **Before dispatch:** the Run stops with no charge. An expired sync deadline instead produces `FAILED` with `TIMED_OUT`.\n- **After dispatch:** the Run continues; its Price determines the final charge.\n- **Already finished:** the request returns `409`.", "href": "/api-reference/runs/stop" } } }, "/v1/balance": { "get": { "tags": [ "Balance" ], "operationId": "balance", "parameters": [], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "balance_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Settled funds in the Workspace, including funds currently held for Runs." }, "held_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Funds reserved for unfinished Runs. A Hold is not a charge." }, "available_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Funds available for new Runs: balance_usd minus held_usd." }, "client": { "type": "object", "properties": { "client_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum_version": { "type": "string" }, "latest_version": { "type": "string" }, "upgrade_command": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "client_version", "minimum_version", "latest_version", "upgrade_command", "reason" ], "additionalProperties": false } }, "required": [ "balance_usd", "held_usd", "available_usd" ], "additionalProperties": false } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidationFailedEncoded" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Check your Workspace's funds and how much is available for new Runs. This free request also confirms that your Key works.", "summary": "Get balance", "x-mint": { "metadata": { "title": "Get balance", "description": "Check your Workspace's funds and how much is available for new Runs. This free request also confirms that your Key works." }, "href": "/api-reference/balance/get" } } }, "/v1/balance/history": { "get": { "tags": [ "Balance" ], "operationId": "balance-history", "parameters": [ { "name": "limit", "in": "query", "schema": { "type": "string", "pattern": "^[+-]?\\d*\\.?\\d+(?:[Ee][+-]?\\d+)?$" }, "required": false }, { "name": "cursor", "in": "query", "schema": { "anyOf": [ { "type": "string", "description": "Pass next_cursor from the previous response to read the next page." }, { "type": "null" } ] }, "required": false }, { "name": "kind", "in": "query", "schema": { "anyOf": [ { "type": "string", "enum": [ "charge", "refund", "topup", "grant", "adjustment" ] }, { "type": "null" } ] }, "required": false } ], "security": [ { "bearer": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "kind": { "type": "string", "enum": [ "charge", "refund", "topup", "grant", "adjustment" ] }, "amount_usd": { "type": "string", "pattern": "^-?(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$" }, "balance_after_usd": { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Workspace balance after this entry." }, "run_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Related Run for a charge or refund; null when no Run is associated." }, "description": { "type": "string" }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" } }, "required": [ "id", "kind", "amount_usd", "balance_after_usd", "run_id", "description", "created_at" ], "additionalProperties": false } }, "next_cursor": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Cursor for the next page. Null when there are no more entries." }, "client": { "type": "object", "properties": { "client_version": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "minimum_version": { "type": "string" }, "latest_version": { "type": "string" }, "upgrade_command": { "type": "string" }, "reason": { "type": "string" } }, "required": [ "client_version", "minimum_version", "latest_version", "upgrade_command", "reason" ], "additionalProperties": false } }, "required": [ "data", "next_cursor" ], "additionalProperties": false } } } }, "400": { "description": "ValidationFailed", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/ValidationFailedEncoded" }, { "$ref": "#/components/schemas/ValidationFailedEncoded" } ] } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedEncoded" } } } }, "403": { "description": "Forbidden", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ForbiddenEncoded" } } } }, "429": { "description": "RateLimited", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RateLimitedEncoded" } } } } }, "description": "Review charges, refunds, top-ups, Grants, and adjustments, newest first. Each entry shows the amount and the balance after it. Filter by kind and use next_cursor to read the next page.", "summary": "List balance history", "x-mint": { "metadata": { "title": "List balance history", "description": "Review charges, refunds, top-ups, Grants, and adjustments, newest first. Each entry shows the amount and the balance after it. Filter by kind and use next_cursor to read the next page." }, "href": "/api-reference/balance/history" } } } }, "components": { "schemas": { "WebResearchResult": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object" }, "output": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "url": { "type": "string", "description": "The requested URL, or the final URL when the Provider reports one." }, "final_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The post-redirect URL as reported by the Provider (Firecrawl, Exa). Null when the Provider does not report one." }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "markdown": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "html": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "raw_html": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "text_character_limit": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "The character cap Glasser asked the Provider to apply to text (10000 for Exa), so text of exactly this length may be truncated. Null when no cap was applied." }, "cached": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "Whether the Provider served the page from its cache (Firecrawl cacheState, Exa status source). Null when the Provider does not say." }, "fetched_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "When the Provider fetched the page, ISO 8601 UTC (DataForSEO fetch_time). Null when the Provider does not report it." }, "quality": { "type": "string", "enum": [ "unverified" ], "description": "Deprecated: always 'unverified'; no content check is applied. Kept for compatibility and will be removed in the next breaking revision." } }, "required": [ "url", "final_url", "title", "text", "markdown", "html", "raw_html", "text_character_limit", "cached", "fetched_at", "quality" ], "additionalProperties": false }, { "type": "object", "properties": { "results": { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google's short excerpt (Serper / SerpApi), or Exa's extracted highlight for Exa. Not the full page text." }, "position": { "type": "integer" }, "date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Deprecated: use published_at or date_text. Holds Google's display text for Serper / SerpApi and Exa's raw publishedDate for Exa." }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC timestamp, filled only when the Provider reports a machine timestamp (Exa publishedDate, SerpApi news iso_date); otherwise null." }, "date_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google's display text exactly as the Provider returned it (Serper / SerpApi date). It may be relative to the Run's completed_at, such as '3 hours ago', and is never parsed." } }, "required": [ "url", "title", "snippet", "position", "date", "published_at", "date_text" ], "additionalProperties": false } } }, "required": [ "results" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publisher or site name as the Provider shows it." }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC timestamp, filled only when the Provider reports a machine timestamp (Exa publishedDate, SerpApi news iso_date); otherwise null." }, "date_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google's display text exactly as the Provider returned it (Serper / SerpApi date). It may be relative to the Run's completed_at, such as '3 hours ago', and is never parsed." }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "url", "source", "published_at", "date_text", "snippet" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Provider's address text, not parsed or completed. Serper may return only the street line." }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rating": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Google's average star rating, 1–5." }, "reviews": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of Google reviews behind the rating." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "google_cid": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google Maps CID of the place (Serper cid, SerpApi data_cid)." } }, "required": [ "name", "address", "category", "rating", "reviews", "phone", "website", "latitude", "longitude", "google_cid" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "publication": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cited_by": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "pdf_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "url", "snippet", "publication", "year", "cited_by", "pdf_url" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Google Shopping product page." }, "merchant_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The merchant's offer URL when the Provider reports one (SerpApi link); null for Serper." }, "google_product_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google Shopping catalog product id (Serper productId, SerpApi product_id)." }, "price_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Provider's display price, such as '$69.00'. Not parsed; the currency follows country." }, "seller": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "rating": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Google's average star rating, 1–5." }, "reviews": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Number of Google reviews behind the rating." }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "url", "merchant_url", "google_product_id", "price_text", "seller", "rating", "reviews", "image_url" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "image_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publisher or site name as the Provider shows it." }, "width": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "height": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "title", "image_url", "thumbnail_url", "source_url", "source", "width", "height" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "channel": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Video platform as the Provider shows it, such as YouTube." }, "date_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Google's display text exactly as the Provider returned it (Serper / SerpApi date). It may be relative to the Run's completed_at, such as '3 hours ago', and is never parsed." }, "duration_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display duration as returned, such as '4:39'." }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "thumbnail_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "title", "url", "channel", "source", "date_text", "duration_text", "snippet", "thumbnail_url" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exa_similarity_score": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Exa's own similarity score for this page. Compare it only within one response; it is not comparable to other Providers' scores." }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC timestamp, filled only when the Provider reports a machine timestamp (Exa publishedDate, SerpApi news iso_date); otherwise null." }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "url", "title", "exa_similarity_score", "published_at", "author" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "answer": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "citations": { "type": "array", "items": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC timestamp, filled only when the Provider reports a machine timestamp (Exa publishedDate, SerpApi news iso_date); otherwise null." } }, "required": [ "url", "title", "published_at" ], "additionalProperties": false } } }, "required": [ "answer", "citations" ], "additionalProperties": false } ] }, { "type": "null" } ], "description": "Normalized fields per action. The Provider's native output is not repeated here; it stays on the Run (GET /v1/runs/:id). Values a Provider does not report are null.\n\n- search: results[]: url, title, snippet (Google's excerpt; Exa's extracted highlight for Exa), position, published_at, date_text, date (deprecated)\n- news: items[]: title, url, source, published_at, date_text, snippet\n- places: items[]: name, address (Provider's text; may be the street line only), category, rating (1–5), reviews, phone, website, latitude, longitude, google_cid\n- scholar: items[]: title, url, snippet, publication, year, cited_by, pdf_url\n- shopping: items[]: title, url (Google Shopping page), merchant_url, google_product_id, price_text, seller, rating (1–5), reviews, image_url\n- images: items[]: title, image_url, thumbnail_url, source_url, source, width, height\n- videos: items[]: title, url, channel, source, date_text, duration_text, snippet, thumbnail_url\n- answer: answer, citations[]: url, title, published_at\n- scrape: url, final_url, title, text, markdown, html, raw_html, text_character_limit, cached, fetched_at, quality (deprecated)\n- similar: items[]: url, title, exa_similarity_score, published_at, author\n\npublished_at is ISO 8601 UTC and set only from a Provider's machine timestamp. date_text is Google's display text as returned; it may be relative to the Run's completed_at and is never parsed. rating is Google's 1–5 star average; reviews is a count. source is a publisher or site name. exa_similarity_score is Exa's own score and is comparable only within one response." }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." }, "error": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when status is COMPLETED.\n\n- For 2xx responses, output contains Provider-native JSON (any shape), or null for an empty body.\n- For non-2xx responses, error contains the Provider's error body and output is null.\n\nSensitive fields are removed from both bodies." }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Total charge of runs in this Solution response. Null until all listed Runs settle. Each Run retains its own charge; failures can also be charged." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Single-Run charge basis, or null for a multi-Run total. Read runs[].charge_basis for each charge." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." }, "action": { "type": "string", "enum": [ "search", "news", "places", "scholar", "shopping", "images", "videos", "answer", "scrape", "similar" ] }, "result_status": { "type": "string", "enum": [ "success", "partial", "no_result", "error", "pending" ], "description": "Business delivery status, independent of the final Run lifecycle in status. success is not a semantic content-quality verdict." }, "missing_formats": { "type": "array", "items": { "type": "string", "enum": [ "text", "markdown", "html", "raw_html" ] } }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "output": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ] }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Final charge as an exact USD decimal string. Null while QUEUED or RUNNING. A FAILED Run can have a non-zero charge under the Endpoint's Price." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Price clause used to calculate the charge. Null before settlement or when no Provider attempt was made." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata" ], "additionalProperties": false } }, "result_url": { "type": "string", "description": "Authenticated, read-only URL path for polling this normalized result and total charge. Use with the API origin. Does not create Runs or resume fallback. GET /v1/runs/:id still returns the native, individual Run." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata", "action", "result_status", "missing_formats", "error", "runs", "result_url" ], "additionalProperties": false }, "ValidationFailedEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "validation_failed" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "IdempotencyKeyRequiredEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "idempotency_key_required" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "IdempotencyConflictEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "idempotency_conflict" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "EndpointNotPermittedEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "endpoint_not_permitted" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "ForbiddenEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "forbidden" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "InsufficientBalanceEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "insufficient_balance" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "ServiceUnavailableEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "service_unavailable" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "RateLimitedEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "UnauthorizedEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "unauthorized" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "NotFoundEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "not_found" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "CompanyIntelligenceResult": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object" }, "output": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company name as the Provider reports it." }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Company website as an http(s) URL." }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Short company description from the Provider." }, "industry": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Industry label in the answering Provider's own vocabulary (LinkedIn, GICS-style, ...). Not comparable across Providers; check `provider`." }, "employees": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Employee count. A Provider's own estimate, not an audited headcount." }, "employee_range_min": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Lower edge of the Provider's employee-size bucket (for example 10000 for 10K-50K)." }, "employee_range_max": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Upper edge of the Provider's employee-size bucket; null for an open-ended bucket such as 10000+." }, "founded_year": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Year the company was founded." }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Headquarters city." }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Headquarters state or region." }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Headquarters country as an English display name (never a code)." }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Headquarters country as an ISO 3166-1 alpha-2 code." }, "linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "LinkedIn company page URL." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Headquarters phone number as the Provider reports it." }, "total_funding_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Total funding raised, USD, as the Provider reports it." }, "revenue_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Annual revenue as a single figure, USD: the Provider's estimate or reported number. Null when the Provider only gives a range (see revenue_range_min_usd / revenue_range_max_usd)." }, "revenue_range_min_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Lower edge of the Provider's annual-revenue bucket, USD." }, "revenue_range_max_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Upper edge of the Provider's annual-revenue bucket, USD; null for an open-ended bucket such as $10B+." }, "ownership": { "anyOf": [ { "type": "string", "enum": [ "public", "private", "nonprofit", "government", "education", "other" ] }, { "type": "null" } ], "description": "Ownership type mapped from the Provider's label. Null when the Provider does not say; private is never inferred." }, "ticker": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Stock ticker or public symbol, for public companies." }, "latest_funding_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Date of the latest funding round, YYYY-MM-DD." } }, "required": [ "name", "website", "description", "industry", "employees", "employee_range_min", "employee_range_max", "founded_year", "city", "region", "country", "country_code", "linkedin_url", "phone", "total_funding_usd", "revenue_usd", "revenue_range_min_usd", "revenue_range_max_usd", "ownership", "ticker", "latest_funding_date" ], "additionalProperties": false }, { "type": "object", "properties": { "monthly_visits": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Monthly visits from all channels, worldwide (Similarweb panel estimate). Not scoped to country." }, "organic_traffic": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Estimated monthly organic search visits in the request country (default us); a search-model estimate." }, "paid_traffic": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Estimated monthly paid search visits in the request country (default us)." }, "organic_keywords": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Keywords the domain ranks for organically in the request country." }, "paid_keywords": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Keywords the domain bids on in the request country." }, "organic_traffic_value_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Estimated monthly value of the organic traffic, USD (Ahrefs). Null for other Providers." }, "similarweb_global_rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Similarweb global rank (1 = most visited). Null for other Providers." }, "bounce_rate": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Bounce rate as a fraction 0-1 (Similarweb)." }, "pages_per_visit": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Pages per visit (Similarweb)." }, "avg_visit_duration_seconds": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Average visit duration in seconds (Similarweb)." } }, "required": [ "monthly_visits", "organic_traffic", "paid_traffic", "organic_keywords", "paid_keywords", "organic_traffic_value_usd", "similarweb_global_rank", "bounce_rate", "pages_per_visit", "avg_visit_duration_seconds" ], "additionalProperties": false }, { "type": "object", "properties": { "total_funding_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Total funding raised, USD, as the Provider reports it." }, "items": { "type": "array", "items": { "type": "object", "properties": { "round_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Date of the round, YYYY-MM-DD. LeadMagic dates are month precision (day 01)." }, "round": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Round label in the answering Provider's vocabulary (seed, Series I, ...)." }, "amount_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Amount raised in the round, USD. Null for other currencies." }, "investors": { "type": "array", "items": { "type": "string" }, "description": "Investor names." }, "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Source article for the round (PredictLeads)." } }, "required": [ "round_date", "round", "amount_usd", "investors", "source_url" ], "additionalProperties": false } } }, "required": [ "total_funding_usd", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "description": "Technology name." }, "categories": { "type": "array", "items": { "type": "string" }, "description": "Category labels in the answering Provider's vocabulary (BuiltWith tag, DataForSEO group/category). Empty when the Provider gives none." }, "detection_source": { "anyOf": [ { "type": "string", "enum": [ "website", "job_postings" ] }, { "type": "null" } ], "description": "How the technology was detected: crawling the public website, or inferred from job postings (PredictLeads behind-the-firewall detections)." }, "predictleads_confidence": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "PredictLeads detection confidence, 0-1. Null for other Providers." }, "first_detected_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First detection date, YYYY-MM-DD." }, "last_detected_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Latest detection date, YYYY-MM-DD." } }, "required": [ "name", "categories", "detection_source", "predictleads_confidence", "first_detected_date", "last_detected_date" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The similar company's domain (hostname without www. or port)." }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The similar company's name. Null when the Provider returns web pages (Exa)." }, "page_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Title of the matched web page (Exa only); not a company name." }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "1-based rank in the Provider's answer." }, "predictleads_similarity_score": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "PredictLeads company-similarity score, 0-1. Null for other Providers." }, "exa_similarity_score": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Exa neural similarity between the company's website and the matched page. Null for other Providers." }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Why the Provider considers the company similar (PredictLeads)." } }, "required": [ "domain", "name", "page_title", "position", "predictleads_similarity_score", "exa_similarity_score", "reason" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Headline." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Article URL." }, "source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Publisher name (Serper). Null when the Provider gives none." }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Article publication time, ISO 8601 UTC." }, "event_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Date the reported event happened, YYYY-MM-DD (PredictLeads)." }, "date_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The Provider's display date exactly as returned (Google News, may be relative to completed_at such as '3 hours ago'); never parsed." }, "category": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Event category in the Provider's vocabulary (PredictLeads)." }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Short excerpt." } }, "required": [ "title", "url", "source", "published_at", "event_date", "date_text", "category", "snippet" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false } ] }, { "type": "null" } ], "description": "Normalized fields per action. The Provider's native output is not repeated here; it stays on the Run (GET /v1/runs/:id). Values a Provider does not report are null; an empty answer is the action's shape with every field null, or items: [], with result_status no_result. Money is USD. Employees and revenue are the Provider's own estimates; *_range_min / *_range_max are the edges of the Provider's bucket. A score from a Provider's own model is named after the Provider (exa_similarity_score) and is null for the others. Labels such as industry, categories, round and category are in the answering Provider's vocabulary.\n\n- enrich: name, website, description, industry, employees, employee_range_min, employee_range_max, founded_year, city, region, country, country_code, linkedin_url, phone, total_funding_usd, revenue_usd, revenue_range_min_usd, revenue_range_max_usd, ownership, ticker, latest_funding_date\n- tech_stack: items[]: name, categories[], detection_source, predictleads_confidence, first_detected_date, last_detected_date\n- traffic: monthly_visits, organic_traffic, paid_traffic, organic_keywords, paid_keywords, organic_traffic_value_usd, similarweb_global_rank, bounce_rate, pages_per_visit, avg_visit_duration_seconds\n- competitors: items[]: domain, name, page_title, position, predictleads_similarity_score, exa_similarity_score, reason\n- funding: total_funding_usd, items[]: round_date, round, amount_usd, investors[], source_url\n- news: items[]: title, url, source, published_at, event_date, date_text, category, snippet" }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." }, "error": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when status is COMPLETED.\n\n- For 2xx responses, output contains Provider-native JSON (any shape), or null for an empty body.\n- For non-2xx responses, error contains the Provider's error body and output is null.\n\nSensitive fields are removed from both bodies." }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Total charge of runs in this Solution response. Null until all listed Runs settle. Each Run retains its own charge; failures can also be charged." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Single-Run charge basis, or null for a multi-Run total. Read runs[].charge_basis for each charge." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." }, "action": { "type": "string", "enum": [ "enrich", "tech_stack", "traffic", "competitors", "funding", "news" ] }, "result_status": { "type": "string", "enum": [ "success", "no_result", "error", "pending" ], "description": "Business delivery status, independent of the final Run lifecycle in status. no_result is an empty but valid answer; error means the Provider output could not be delivered." }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "output": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ] }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Final charge as an exact USD decimal string. Null while QUEUED or RUNNING. A FAILED Run can have a non-zero charge under the Endpoint's Price." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Price clause used to calculate the charge. Null before settlement or when no Provider attempt was made." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata" ], "additionalProperties": false } }, "result_url": { "type": "string", "description": "Authenticated, read-only URL path for polling this normalized result and total charge. Use with the API origin. Does not create Runs or resume fallback. GET /v1/runs/:id still returns the native, individual Run." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata", "action", "result_status", "error", "runs", "result_url" ], "additionalProperties": false }, "PeopleSearchResult": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object" }, "output": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "total_matches": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "People matching the filters in the Provider's whole dataset, not only this page. Null when the Provider gives only the page count (LeadMagic)." }, "items": { "type": "array", "items": { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full name exactly as the Provider reports it (PDL is lower case). Null when the Provider gives only first and last name; never joined." }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name as the Provider reports it." }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name as the Provider reports it. Null when the Provider masks it (Apollo search)." }, "job_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current job title as the Provider reports it." }, "seniority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Seniority label in the answering Provider's own vocabulary (Apollo founder, PDL cxo, LeadMagic C-Team, Hunter executive). Not the request's seniorities vocabulary and not comparable across Providers; check provider. When the Provider lists several, the first." }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Department or job function in the answering Provider's own vocabulary. When the Provider lists several, the first." }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Profile headline (the LinkedIn job-title line)." }, "linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "LinkedIn profile URL. https:// is added when the Provider omits a scheme." }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City of the person's location." }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or region of the person's location." }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country of the person's location as an English display name (never a code)." }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country of the person's location as an ISO 3166-1 alpha-2 code." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Work email as the Provider reports it. PDL: work_email only; its other addresses stay on the Run." }, "email_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The answering Provider's own verification label for email (Apollo verified, Prospeo VERIFIED, Hunter and LeadMagic valid). Providers verify differently, so the labels are not comparable; read it with email_catch_all and email_source." }, "email_catch_all": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True when the Provider reports that the email's domain accepts every address, so a mailbox check cannot confirm this one (Hunter accept_all, Apollo email_domain_catchall)." }, "email_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How Hunter got the email: found (seen on the web) or generated (built from the domain's address pattern). Null for other Providers." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number as the Provider reports it. Masked numbers are left out." }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current employer as the Provider reports it." }, "company_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current employer's domain (hostname without www. or port)." }, "company_linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current employer's LinkedIn company page URL." }, "apollo_match_confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Apollo's confidence that the record matches the input: high, medium, low or none. Null for other Providers." }, "pdl_likelihood": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "People Data Labs' 1-10 score for how well the record matches the input. Null for other Providers." }, "hunter_email_score": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Hunter's 0-100 confidence in email (email-finder score, domain-search confidence). Null for other Providers." }, "zoominfo_accuracy_score": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "ZoomInfo's 0-100 contact accuracy score. Null for other Providers." } }, "required": [ "name", "first_name", "last_name", "job_title", "seniority", "department", "headline", "linkedin_url", "city", "region", "country", "country_code", "email", "email_status", "email_catch_all", "email_source", "phone", "company_name", "company_domain", "company_linkedin_url", "apollo_match_confidence", "pdl_likelihood", "hunter_email_score", "zoominfo_accuracy_score" ], "additionalProperties": false } } }, "required": [ "total_matches", "items" ], "additionalProperties": false }, { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Full name exactly as the Provider reports it (PDL is lower case). Null when the Provider gives only first and last name; never joined." }, "first_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "First name as the Provider reports it." }, "last_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Last name as the Provider reports it. Null when the Provider masks it (Apollo search)." }, "job_title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current job title as the Provider reports it." }, "seniority": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Seniority label in the answering Provider's own vocabulary (Apollo founder, PDL cxo, LeadMagic C-Team, Hunter executive). Not the request's seniorities vocabulary and not comparable across Providers; check provider. When the Provider lists several, the first." }, "department": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Department or job function in the answering Provider's own vocabulary. When the Provider lists several, the first." }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Profile headline (the LinkedIn job-title line)." }, "linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "LinkedIn profile URL. https:// is added when the Provider omits a scheme." }, "city": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "City of the person's location." }, "region": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "State or region of the person's location." }, "country": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country of the person's location as an English display name (never a code)." }, "country_code": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Country of the person's location as an ISO 3166-1 alpha-2 code." }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Work email as the Provider reports it. PDL: work_email only; its other addresses stay on the Run." }, "email_status": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The answering Provider's own verification label for email (Apollo verified, Prospeo VERIFIED, Hunter and LeadMagic valid). Providers verify differently, so the labels are not comparable; read it with email_catch_all and email_source." }, "email_catch_all": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ], "description": "True when the Provider reports that the email's domain accepts every address, so a mailbox check cannot confirm this one (Hunter accept_all, Apollo email_domain_catchall)." }, "email_source": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "How Hunter got the email: found (seen on the web) or generated (built from the domain's address pattern). Null for other Providers." }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Phone number as the Provider reports it. Masked numbers are left out." }, "company_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current employer as the Provider reports it." }, "company_domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current employer's domain (hostname without www. or port)." }, "company_linkedin_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Current employer's LinkedIn company page URL." }, "apollo_match_confidence": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Apollo's confidence that the record matches the input: high, medium, low or none. Null for other Providers." }, "pdl_likelihood": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "People Data Labs' 1-10 score for how well the record matches the input. Null for other Providers." }, "hunter_email_score": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "Hunter's 0-100 confidence in email (email-finder score, domain-search confidence). Null for other Providers." }, "zoominfo_accuracy_score": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "ZoomInfo's 0-100 contact accuracy score. Null for other Providers." } }, "required": [ "name", "first_name", "last_name", "job_title", "seniority", "department", "headline", "linkedin_url", "city", "region", "country", "country_code", "email", "email_status", "email_catch_all", "email_source", "phone", "company_name", "company_domain", "company_linkedin_url", "apollo_match_confidence", "pdl_likelihood", "hunter_email_score", "zoominfo_accuracy_score" ], "additionalProperties": false } ] }, { "type": "null" } ], "description": "Normalized fields per action; enrich and find_email return one person with the same fields as a search row. The Provider's native output is not repeated here; it stays on the Run (GET /v1/runs/:id). Values a Provider does not report are null; an empty answer is the action's shape with every field null, or items: [], with result_status no_result. Names, titles and labels are as the Provider reports them. A score from a Provider's own model is named after the Provider (pdl_likelihood) and is null for the others.\n\n- search: total_matches, items[]: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score\n- enrich: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score\n- find_email: name, first_name, last_name, job_title, seniority, department, headline, linkedin_url, city, region, country, country_code, email, email_status, email_catch_all, email_source, phone, company_name, company_domain, company_linkedin_url, apollo_match_confidence, pdl_likelihood, hunter_email_score, zoominfo_accuracy_score" }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." }, "error": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when status is COMPLETED.\n\n- For 2xx responses, output contains Provider-native JSON (any shape), or null for an empty body.\n- For non-2xx responses, error contains the Provider's error body and output is null.\n\nSensitive fields are removed from both bodies." }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Total charge of runs in this Solution response. Null until all listed Runs settle. Each Run retains its own charge; failures can also be charged." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Single-Run charge basis, or null for a multi-Run total. Read runs[].charge_basis for each charge." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." }, "action": { "type": "string", "enum": [ "search", "enrich", "find_email" ] }, "result_status": { "type": "string", "enum": [ "success", "no_result", "error", "pending" ], "description": "Business delivery status, independent of the final Run lifecycle in status. no_result is an empty but valid answer; error means the Provider output could not be delivered." }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "output": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ] }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Final charge as an exact USD decimal string. Null while QUEUED or RUNNING. A FAILED Run can have a non-zero charge under the Endpoint's Price." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Price clause used to calculate the charge. Null before settlement or when no Provider attempt was made." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata" ], "additionalProperties": false } }, "result_url": { "type": "string", "description": "Authenticated, read-only URL path for polling this normalized result and total charge. Use with the API origin. Does not create Runs or resume fallback. GET /v1/runs/:id still returns the native, individual Run." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata", "action", "result_status", "error", "runs", "result_url" ], "additionalProperties": false }, "SeoResearchResult": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object" }, "output": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "volume": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cpc_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "semrush_keyword_difficulty": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "serpstat_keyword_difficulty": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "dataforseo_keyword_difficulty": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "ahrefs_keyword_difficulty": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "intent": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "keyword", "volume", "cpc_usd", "semrush_keyword_difficulty", "serpstat_keyword_difficulty", "dataforseo_keyword_difficulty", "ahrefs_keyword_difficulty", "intent" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "snippet": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "position", "url", "domain", "title", "snippet" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "organic_keywords": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "organic_traffic": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "organic_traffic_value_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "paid_keywords": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "paid_traffic": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] } }, "required": [ "organic_keywords", "organic_traffic", "organic_traffic_value_usd", "paid_keywords", "paid_traffic" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "position": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "volume": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cpc_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "traffic": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] } }, "required": [ "keyword", "position", "url", "volume", "cpc_usd", "traffic" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "common_keywords": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "organic_keywords": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "organic_traffic": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] } }, "required": [ "domain", "common_keywords", "organic_keywords", "organic_traffic" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "backlinks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "referring_domains": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "semrush_authority_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "dataforseo_rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "serpstat_domain_rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "dofollow_backlinks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "nofollow_backlinks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "backlinks", "referring_domains", "semrush_authority_score", "dataforseo_rank", "serpstat_domain_rank", "dofollow_backlinks", "nofollow_backlinks" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "source_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "target_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "anchor": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "source_ahrefs_domain_rating": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "source_semrush_authority_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "source_dataforseo_rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "dofollow": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] }, "first_seen_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "source_url", "target_url", "anchor", "source_ahrefs_domain_rating", "source_semrush_authority_score", "source_dataforseo_rank", "dofollow", "first_seen_at" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "ahrefs_domain_rating": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "semrush_authority_score": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "dataforseo_rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "backlinks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "dofollow_backlinks": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "first_seen_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "domain", "ahrefs_domain_rating", "semrush_authority_score", "dataforseo_rank", "backlinks", "dofollow_backlinks", "first_seen_at" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "ahrefs_domain_rating": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] } }, "required": [ "ahrefs_domain_rating" ], "additionalProperties": false }, { "type": "object", "properties": { "dataforseo_task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crawl_progress": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "crawl_stop_reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "pages_crawled": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "dataforseo_onpage_score": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "broken_links": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "non_indexable": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "duplicate_title": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "duplicate_description": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "duplicate_content": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "dataforseo_task_id", "crawl_progress", "crawl_stop_reason", "pages_crawled", "dataforseo_onpage_score", "broken_links", "non_indexable", "duplicate_title", "duplicate_description", "duplicate_content" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "keyword": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "volume": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "cpc_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "semrush_keyword_difficulty": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "dataforseo_keyword_difficulty": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "positions": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } } }, "required": [ "keyword", "volume", "cpc_usd", "semrush_keyword_difficulty", "dataforseo_keyword_difficulty", "positions" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "domain": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dataforseo_rank": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "backlinks_per_target": { "type": "object", "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } } }, "required": [ "domain", "dataforseo_rank", "backlinks_per_target" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "status_code": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "description": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "canonical": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "dataforseo_onpage_score": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "internal_links": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "external_links": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "url", "status_code", "title", "description", "canonical", "dataforseo_onpage_score", "internal_links", "external_links" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "month": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "organic_keywords": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "organic_traffic": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "organic_traffic_value_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "paid_keywords": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "paid_traffic": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] } }, "required": [ "month", "organic_keywords", "organic_traffic", "organic_traffic_value_usd", "paid_keywords", "paid_traffic" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mentions": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "ai_search_volume": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "is_target_domain": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "url", "platform", "mentions", "ai_search_volume", "is_target_domain" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "ahrefs_ai_citations": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "ahrefs_ai_cited_pages": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "ahrefs_ai_citations_by_platform": { "anyOf": [ { "type": "object", "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, { "type": "null" } ] }, "dataforseo_ai_mentions_by_platform": { "anyOf": [ { "type": "object", "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, { "type": "null" } ] }, "dataforseo_ai_search_volume_by_platform": { "anyOf": [ { "type": "object", "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, { "type": "null" } ] } }, "required": [ "ahrefs_ai_citations", "ahrefs_ai_cited_pages", "ahrefs_ai_citations_by_platform", "dataforseo_ai_mentions_by_platform", "dataforseo_ai_search_volume_by_platform" ], "additionalProperties": false } ] }, { "type": "null" } ], "description": "Normalized fields per action. The Provider's native output is not repeated here; it stays on the Run (GET /v1/runs/:id). Values a Provider does not report are null. Money is USD. Authority scores keep the answering Provider's own metric and name and are never converted: ahrefs_domain_rating (Ahrefs Domain Rating, 0–100), semrush_authority_score (Semrush Authority Score, 0–100), dataforseo_rank (DataForSEO rank, 0–1000), serpstat_domain_rank (Serpstat Domain Rank, 0–100). Keyword difficulty is split the same way (semrush_keyword_difficulty, serpstat_keyword_difficulty, dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, each 0–100 on its own model). Only the field of the Provider that answered is filled; the others are null. volume, traffic and cpc are the answering Provider's estimates; compare them only within one Provider (runs[].provider). An empty answer (result_status no_result) keeps the action's shape: items is [], or every field is null.\n\n- keyword_overview: items[]: keyword, volume, cpc_usd, semrush_keyword_difficulty, serpstat_keyword_difficulty, dataforseo_keyword_difficulty, ahrefs_keyword_difficulty, intent\n- keyword_ideas: items[]: same row as keyword_overview\n- serp: items[]: position (organic position: 1 = first organic result; SERP features not counted), url, domain, title, snippet (organic results only)\n- domain_overview: organic_keywords, organic_traffic, organic_traffic_value_usd, paid_keywords, paid_traffic\n- ranked_keywords: items[]: keyword, position (organic position: 1 = first organic result; SERP features not counted), url, volume, cpc_usd, traffic\n- organic_competitors: items[]: domain, common_keywords, organic_keywords (the competitor's total), organic_traffic (the target domain and its subdomains are left out)\n- backlinks_overview: backlinks, referring_domains, semrush_authority_score, dataforseo_rank, serpstat_domain_rank, dofollow_backlinks, nofollow_backlinks\n- backlinks: items[]: source_url, target_url, anchor, source_ahrefs_domain_rating, source_semrush_authority_score, source_dataforseo_rank, dofollow, first_seen_at (ISO 8601 UTC; Semrush: zone not stated, no Z suffix). One row per link from every Provider\n- referring_domains: items[]: domain, ahrefs_domain_rating, semrush_authority_score, dataforseo_rank, backlinks, dofollow_backlinks, first_seen_at (ISO 8601 UTC; Semrush: zone not stated, no Z suffix)\n- domain_rating: ahrefs_domain_rating\n- site_audit: dataforseo_task_id (input to DataForSEO's OnPage report endpoints), crawl_progress, crawl_stop_reason (DataForSEO's vocabulary), pages_crawled, dataforseo_onpage_score, broken_links, non_indexable, duplicate_title, duplicate_description, duplicate_content\n- keyword_gap: items[]: keyword, volume, cpc_usd, semrush_keyword_difficulty, dataforseo_keyword_difficulty, positions {domain: organic position; null = not in the top 100}, keyed by the domains sent. Semrush rows are keywords any of the domains ranks for (union); DataForSEO rows are keywords the competitor ranks for and you do not\n- backlink_gap: items[]: domain, dataforseo_rank, backlinks_per_target {competitor domain: count}\n- page_audit: url, status_code, title, description, canonical, dataforseo_onpage_score, internal_links, external_links\n- visibility_history: items[]: month, organic_keywords, organic_traffic, organic_traffic_value_usd, paid_keywords, paid_traffic\n- ai_citations: items[]: url, platform, mentions, ai_search_volume, is_target_domain (pages most cited in AI answers that mention the domain, from any site)\n- ai_visibility: ahrefs_ai_citations, ahrefs_ai_cited_pages, ahrefs_ai_citations_by_platform {platform: citations}, dataforseo_ai_mentions_by_platform {platform: mentions}, dataforseo_ai_search_volume_by_platform {platform: AI search volume}. Each Provider fills only its own fields; no cross-Provider total" }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." }, "error": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when status is COMPLETED.\n\n- For 2xx responses, output contains Provider-native JSON (any shape), or null for an empty body.\n- For non-2xx responses, error contains the Provider's error body and output is null.\n\nSensitive fields are removed from both bodies." }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Total charge of runs in this Solution response. Null until all listed Runs settle. Each Run retains its own charge; failures can also be charged." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Single-Run charge basis, or null for a multi-Run total. Read runs[].charge_basis for each charge." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." }, "action": { "type": "string", "enum": [ "keyword_overview", "keyword_ideas", "serp", "domain_overview", "ranked_keywords", "organic_competitors", "backlinks_overview", "backlinks", "referring_domains", "domain_rating", "site_audit", "ai_visibility", "keyword_gap", "backlink_gap", "page_audit", "visibility_history", "ai_citations" ] }, "result_status": { "type": "string", "enum": [ "success", "no_result", "error", "pending" ], "description": "Business delivery status, independent of the final Run lifecycle in status. no_result is an empty but valid answer; error means the Provider output could not be delivered." }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "output": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ] }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Final charge as an exact USD decimal string. Null while QUEUED or RUNNING. A FAILED Run can have a non-zero charge under the Endpoint's Price." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Price clause used to calculate the charge. Null before settlement or when no Provider attempt was made." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata" ], "additionalProperties": false } }, "result_url": { "type": "string", "description": "Authenticated, read-only URL path for polling this normalized result and total charge. Use with the API origin. Does not create Runs or resume fallback. GET /v1/runs/:id still returns the native, individual Run." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata", "action", "result_status", "error", "runs", "result_url" ], "additionalProperties": false }, "SocialResearchResult": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object" }, "output": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bio": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Free-text description (LinkedIn: the About section)." }, "headline": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "LinkedIn person headline (job title line); null on other platforms." }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The account's own website: LinkedIn company website, X profile link (expanded, never t.co); null elsewhere." }, "followers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Followers; Reddit: subreddit subscribers; YouTube: subscribers." }, "following": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Accounts this account follows. Null on Reddit, YouTube and LinkedIn." }, "posts": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "verified": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "platform", "handle", "name", "url", "bio", "headline", "website", "followers", "following", "posts", "verified" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The platform's post id. LinkedIn: the bare activity id (no urn:li:activity: prefix)." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reddit and YouTube title; null on other platforms." }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The post body: Reddit self-text, YouTube description, the tweet, caption or post text. Null when the Provider returns no body (a Reddit link post, a YouTube search result)." }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name, or the handle where the platform shows no other name (X, TikTok, Instagram, Reddit)." }, "author_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC publish time; null when the Provider gives no exact time." }, "likes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Reddit: net score (upvotes minus downvotes, can be negative). X: favorites. TikTok: diggs. Others: likes or reactions." }, "comments": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "shares": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "X: retweets. TikTok: share count (share-sheet sends, not reposts). LinkedIn: reposts. Null on Reddit, YouTube and Instagram." }, "views": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "X: impressions. TikTok: plays. YouTube: views. Instagram: video views. Null on Reddit and LinkedIn." } }, "required": [ "id", "url", "title", "text", "author", "author_url", "published_at", "likes", "comments", "shares", "views" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "id": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The platform's post id. LinkedIn: the bare activity id (no urn:li:activity: prefix)." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "title": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Reddit and YouTube title; null on other platforms." }, "text": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The post body: Reddit self-text, YouTube description, the tweet, caption or post text. Null when the Provider returns no body (a Reddit link post, a YouTube search result)." }, "author": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Display name, or the handle where the platform shows no other name (X, TikTok, Instagram, Reddit)." }, "author_url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "published_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "ISO 8601 UTC publish time; null when the Provider gives no exact time." }, "likes": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "Reddit: net score (upvotes minus downvotes, can be negative). X: favorites. TikTok: diggs. Others: likes or reactions." }, "comments": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "shares": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "X: retweets. TikTok: share count (share-sheet sends, not reposts). LinkedIn: reposts. Null on Reddit, YouTube and Instagram." }, "views": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "X: impressions. TikTok: plays. YouTube: views. Instagram: video views. Null on Reddit and LinkedIn." } }, "required": [ "id", "url", "title", "text", "author", "author_url", "published_at", "likes", "comments", "shares", "views" ], "additionalProperties": false }, { "type": "object", "properties": { "profiles": { "type": "array", "items": { "type": "object", "properties": { "platform": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "Lower-case network name. The six social_research platforms use their request names (twitter is x); other networks (facebook, github, …) pass through." }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "handle": { "anyOf": [ { "type": "string" }, { "type": "null" } ], "description": "The username on that network, usable as social_research `handle`; null when the Provider has none." }, "scrapecreators_confidence": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ], "description": "ScrapeCreators' 0–1 confidence that this profile belongs to the account. Null on other Providers." }, "followers": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "reddit.find: subreddit subscribers. Null on other platforms." } }, "required": [ "platform", "url", "handle", "scrapecreators_confidence", "followers" ], "additionalProperties": false } }, "pdl_likelihood": { "anyOf": [ { "type": "integer" }, { "type": "null" } ], "description": "People Data Labs' 1–10 score for how well the person record matches the input; it covers the whole person, not one profile. linkedin.find only; null elsewhere." } }, "required": [ "profiles", "pdl_likelihood" ], "additionalProperties": false } ] }, { "type": "null" } ], "description": "Normalized fields per mode, shared by every platform. The Provider's native output is not repeated here; it stays on the Run (GET /v1/runs/:id). Values a platform or Provider does not report are null.\n\n- profile: platform, handle, name, url, bio, headline, website, followers, following, posts, verified\n- search: items[]: id, url, title, text, author, author_url, published_at, likes, comments, shares, views\n- feed: items[]: same post fields as search\n- post: id, url, title, text, author, author_url, published_at, likes, comments, shares, views\n- find: profiles[]: platform, url, handle, scrapecreators_confidence, followers (Reddit: matching subreddits); pdl_likelihood" }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." }, "error": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when status is COMPLETED.\n\n- For 2xx responses, output contains Provider-native JSON (any shape), or null for an empty body.\n- For non-2xx responses, error contains the Provider's error body and output is null.\n\nSensitive fields are removed from both bodies." }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Total charge of runs in this Solution response. Null until all listed Runs settle. Each Run retains its own charge; failures can also be charged." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Single-Run charge basis, or null for a multi-Run total. Read runs[].charge_basis for each charge." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." }, "action": { "type": "string", "pattern": "^[a-z]+\\.[a-z]+$", "description": "`.`; a LinkedIn company page in profile mode is linkedin.company." }, "result_status": { "type": "string", "enum": [ "success", "no_result", "error", "pending" ], "description": "Business delivery status, independent of the final Run lifecycle in status. no_result is an empty but valid answer; error means the Provider output could not be delivered." }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "output": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ] }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Final charge as an exact USD decimal string. Null while QUEUED or RUNNING. A FAILED Run can have a non-zero charge under the Endpoint's Price." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Price clause used to calculate the charge. Null before settlement or when no Provider attempt was made." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata" ], "additionalProperties": false } }, "result_url": { "type": "string", "description": "Authenticated, read-only URL path for polling this normalized result and total charge. Use with the API origin. Does not create Runs or resume fallback. GET /v1/runs/:id still returns the native, individual Run." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata", "action", "result_status", "error", "runs", "result_url" ], "additionalProperties": false }, "MarketDataResult": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object" }, "output": { "anyOf": [ { "anyOf": [ { "type": "object", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "property_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bedrooms": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "bathrooms": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "living_area_sqft": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lot_size_sqft": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "year_built": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "estimated_value_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "value_low_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "value_high_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "comparables_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "address", "property_type", "bedrooms", "bathrooms", "living_area_sqft", "lot_size_sqft", "year_built", "latitude", "longitude", "estimated_value_usd", "value_low_usd", "value_high_usd", "comparables_count" ], "additionalProperties": false }, { "type": "object", "properties": { "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "property_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bedrooms": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "bathrooms": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "living_area_sqft": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lot_size_sqft": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "year_built": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "estimated_rent_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "rent_low_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "rent_high_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "comparables_count": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "address", "property_type", "bedrooms", "bathrooms", "living_area_sqft", "lot_size_sqft", "year_built", "latitude", "longitude", "estimated_rent_usd", "rent_low_usd", "rent_high_usd", "comparables_count" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "property_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "property_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bedrooms": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "bathrooms": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "living_area_sqft": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lot_size_sqft": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "year_built": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "last_sale_price_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "last_sale_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner_names": { "anyOf": [ { "type": "array", "items": { "type": "string" } }, { "type": "null" } ] }, "owner_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner_mailing_address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "owner_occupied": { "anyOf": [ { "type": "boolean" }, { "type": "null" } ] } }, "required": [ "property_id", "address", "property_type", "bedrooms", "bathrooms", "living_area_sqft", "lot_size_sqft", "year_built", "latitude", "longitude", "last_sale_price_usd", "last_sale_date", "owner_names", "owner_type", "owner_mailing_address", "owner_occupied" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "listing_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "property_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bedrooms": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "bathrooms": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "living_area_sqft": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lot_size_sqft": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "year_built": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "listing_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "listed_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "days_on_market": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "hoa_fee_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "mls_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mls_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agent": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "phone", "email", "website" ], "additionalProperties": false }, { "type": "null" } ] }, "office": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "phone", "email", "website" ], "additionalProperties": false }, { "type": "null" } ] }, "price_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] } }, "required": [ "listing_id", "address", "property_type", "bedrooms", "bathrooms", "living_area_sqft", "lot_size_sqft", "year_built", "latitude", "longitude", "status", "listing_type", "listed_date", "days_on_market", "hoa_fee_usd", "mls_name", "mls_number", "agent", "office", "price_usd" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "listing_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "address": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "property_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "bedrooms": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "bathrooms": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "living_area_sqft": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "lot_size_sqft": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "year_built": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "latitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "longitude": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "listing_type": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "listed_date": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "days_on_market": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "hoa_fee_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "mls_name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "mls_number": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "agent": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "phone", "email", "website" ], "additionalProperties": false }, { "type": "null" } ] }, "office": { "anyOf": [ { "type": "object", "properties": { "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "phone": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "email": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "website": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "name", "phone", "email", "website" ], "additionalProperties": false }, { "type": "null" } ] }, "monthly_rent_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] } }, "required": [ "listing_id", "address", "property_type", "bedrooms", "bathrooms", "living_area_sqft", "lot_size_sqft", "year_built", "latitude", "longitude", "status", "listing_type", "listed_date", "days_on_market", "hoa_fee_usd", "mls_name", "mls_number", "agent", "office", "monthly_rent_usd" ], "additionalProperties": false } } }, "required": [ "items" ], "additionalProperties": false }, { "type": "object", "properties": { "zip": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "updated_at": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "sale": { "anyOf": [ { "type": "object", "properties": { "average_price_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "median_price_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "average_price_per_sqft_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "median_price_per_sqft_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "average_days_on_market": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "median_days_on_market": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "total_listings": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "new_listings": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "average_price_usd", "median_price_usd", "average_price_per_sqft_usd", "median_price_per_sqft_usd", "average_days_on_market", "median_days_on_market", "total_listings", "new_listings" ], "additionalProperties": false }, { "type": "null" } ] }, "rental": { "anyOf": [ { "type": "object", "properties": { "average_rent_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "median_rent_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "average_rent_per_sqft_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "median_rent_per_sqft_usd": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "average_days_on_market": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "median_days_on_market": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "total_listings": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, "new_listings": { "anyOf": [ { "type": "integer" }, { "type": "null" } ] } }, "required": [ "average_rent_usd", "median_rent_usd", "average_rent_per_sqft_usd", "median_rent_per_sqft_usd", "average_days_on_market", "median_days_on_market", "total_listings", "new_listings" ], "additionalProperties": false }, { "type": "null" } ] } }, "required": [ "zip", "updated_at", "sale", "rental" ], "additionalProperties": false }, { "type": "object", "properties": { "symbol": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "name": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "exchange": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "currency": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "price": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "change": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "change_percent": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "extended_hours_session": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "extended_hours_price": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "extended_hours_change": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "extended_hours_change_percent": { "anyOf": [ { "anyOf": [ { "type": "number" }, { "type": "string", "enum": [ "Infinity", "-Infinity", "NaN" ] } ] }, { "type": "null" } ] }, "as_of_text": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "symbol", "name", "exchange", "currency", "price", "change", "change_percent", "extended_hours_session", "extended_hours_price", "extended_hours_change", "extended_hours_change_percent", "as_of_text" ], "additionalProperties": false } ] }, { "type": "null" } ], "description": "Normalized fields per action. The Provider's native output is not repeated here; it stays on the Run (GET /v1/runs/:id). Values a Provider does not report are null; an empty answer keeps the action's shape with every field null (or items: []) and result_status no_result. Money is USD unless the action carries a currency field. Dates named *_date are YYYY-MM-DD, *_at are ISO 8601 UTC, and *_text is display text exactly as returned.\n\n- property_value: address, property_type, bedrooms, bathrooms, living_area_sqft (living area), lot_size_sqft, year_built, latitude, longitude, estimated_value_usd, value_low_usd, value_high_usd, comparables_count (number of comparable sales behind the estimate)\n- property_rent: address, property_type, bedrooms, bathrooms, living_area_sqft (living area), lot_size_sqft, year_built, latitude, longitude, estimated_rent_usd (monthly), rent_low_usd, rent_high_usd, comparables_count (number of comparable rentals behind the estimate)\n- property_search: items[]: property_id, address, property_type, bedrooms, bathrooms, living_area_sqft (living area), lot_size_sqft, year_built, latitude, longitude, last_sale_price_usd, last_sale_date (YYYY-MM-DD), owner_names[], owner_type, owner_mailing_address, owner_occupied\n- listings_sale: items[]: listing_id, address, property_type, bedrooms, bathrooms, living_area_sqft (living area), lot_size_sqft, year_built, latitude, longitude, status, listing_type, listed_date (YYYY-MM-DD), days_on_market, hoa_fee_usd (monthly HOA fee), mls_name, mls_number, agent {name, phone, email, website}, office {name, phone, email, website}, price_usd (asking price)\n- listings_rental: items[]: listing_id, address, property_type, bedrooms, bathrooms, living_area_sqft (living area), lot_size_sqft, year_built, latitude, longitude, status, listing_type, listed_date (YYYY-MM-DD), days_on_market, hoa_fee_usd (monthly HOA fee), mls_name, mls_number, agent {name, phone, email, website}, office {name, phone, email, website}, monthly_rent_usd\n- market_stats: zip, updated_at (ISO 8601 UTC, when RentCast last refreshed the aggregate), sale {average_price_usd, median_price_usd, average_price_per_sqft_usd, median_price_per_sqft_usd, average_days_on_market, median_days_on_market, total_listings, new_listings}, rental {average_rent_usd, median_rent_usd, average_rent_per_sqft_usd, median_rent_per_sqft_usd (monthly rent), average_days_on_market, median_days_on_market, total_listings, new_listings}\n- stock_quote: symbol, name, exchange, currency, price (regular-session last price, in currency; Google Finance quotes may be delayed), change (absolute, in currency, vs the previous regular close), change_percent (percent points vs the previous regular close: 1.5 = 1.5%), extended_hours_session (the session label as shown, e.g. Pre-market or After hours; null during regular hours), extended_hours_price, extended_hours_change and extended_hours_change_percent (the extended-hours quote vs the regular-session price, same units), as_of_text (the Google Finance page timestamp exactly as shown, not ISO and not the time of price)" }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." }, "error": { "anyOf": [ {}, { "type": "null" } ] } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ], "description": "Non-null only when status is COMPLETED.\n\n- For 2xx responses, output contains Provider-native JSON (any shape), or null for an empty body.\n- For non-2xx responses, error contains the Provider's error body and output is null.\n\nSensitive fields are removed from both bodies." }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Total charge of runs in this Solution response. Null until all listed Runs settle. Each Run retains its own charge; failures can also be charged." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Single-Run charge basis, or null for a multi-Run total. Read runs[].charge_basis for each charge." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." }, "action": { "type": "string", "enum": [ "property_value", "property_rent", "property_search", "listings_sale", "listings_rental", "market_stats", "stock_quote" ] }, "result_status": { "type": "string", "enum": [ "success", "no_result", "error", "pending" ], "description": "Business delivery status, independent of the final Run lifecycle in status. no_result is an empty but valid answer; error means the Provider output could not be delivered." }, "error": { "anyOf": [ { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "additionalProperties": false }, { "type": "null" } ] }, "runs": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "run_url": { "type": "string", "description": "Open this Run in the console. Requires Workspace membership." }, "provider": { "type": "string", "pattern": "^[a-z0-9][a-z0-9-]*$" }, "endpoint": { "type": "string", "pattern": "^\\/.+$" }, "endpoint_version": { "type": "integer", "exclusiveMinimum": 0 }, "status": { "type": "string", "enum": [ "QUEUED", "RUNNING", "COMPLETED", "FAILED", "STOPPED" ], "description": "QUEUED or RUNNING: still in progress. COMPLETED: a Provider response is available, including non-2xx responses. FAILED: read failure. STOPPED: stopped before dispatch. Read charge_usd separately from status." }, "failure": { "anyOf": [ { "type": "object", "properties": { "kind": { "type": "string", "enum": [ "TIMED_OUT", "INTERNAL" ] }, "message": { "type": "string" } }, "required": [ "kind", "message" ], "additionalProperties": false }, { "type": "null" } ], "description": "Why the Run failed. Non-null only when status is FAILED." }, "input": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "output": { "type": "object", "properties": { "omitted": { "type": "boolean", "enum": [ true ] } }, "required": [ "omitted" ], "additionalProperties": false }, "provider_response": { "anyOf": [ { "type": "object", "properties": { "http_status": { "type": "integer", "minimum": 100, "maximum": 599, "description": "HTTP status returned by the Provider. Check this even when the Run is COMPLETED." } }, "required": [ "http_status" ], "additionalProperties": false }, { "type": "null" } ] }, "charge_usd": { "anyOf": [ { "type": "string", "pattern": "^(0|[1-9]\\d*)\\.(\\d{2}|\\d{2}\\d{0,3}[1-9])$", "description": "Exact USD decimal string (min 2, max 6 decimals, one canonical spelling). Sum with decimal arithmetic or scale by 10^6 — never floats." }, { "type": "null" } ], "description": "Final charge as an exact USD decimal string. Null while QUEUED or RUNNING. A FAILED Run can have a non-zero charge under the Endpoint's Price." }, "charge_basis": { "anyOf": [ { "type": "object", "properties": { "clause": { "type": "string", "enum": [ "rule", "NO_RESULT", "PROVIDER_ERROR", "TIMED_OUT", "INTERNAL" ] }, "quantity": { "anyOf": [ { "type": "integer", "minimum": 0 }, { "type": "null" } ] } }, "required": [ "clause", "quantity" ], "additionalProperties": false }, { "type": "null" } ], "description": "Price clause used to calculate the charge. Null before settlement or when no Provider attempt was made." }, "stoppable": { "type": "boolean", "description": "Whether a stop request can currently be accepted. This does not guarantee that the Run can stop before dispatch." }, "stop_requested_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ], "description": "When a stop was requested. The Run can still continue if dispatch had already started." }, "created_at": { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, "started_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "completed_at": { "anyOf": [ { "type": "string", "description": "ISO-8601 UTC timestamp", "format": "date-time" }, { "type": "null" } ] }, "task_id": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "metadata": { "type": "object", "additionalProperties": { "type": "string", "minLength": 1, "maxLength": 500 }, "maxProperties": 20, "propertyNames": { "type": "string", "pattern": "^[a-z][a-z0-9_]{0,39}$" }, "description": "Your stored tracking fields. Use them to filter Runs. They never go to the Provider or affect routing, Price, or idempotency.\n\n- Up to 20 keys: lowercase letters, digits, and underscores; start with a letter; at most 40 characters.\n- Values: strings of 1–500 characters.\n- user_id: your End user's opaque ID, never their email address or name." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata" ], "additionalProperties": false } }, "result_url": { "type": "string", "description": "Authenticated, read-only URL path for polling this normalized result and total charge. Use with the API origin. Does not create Runs or resume fallback. GET /v1/runs/:id still returns the native, individual Run." } }, "required": [ "id", "run_url", "provider", "endpoint", "endpoint_version", "status", "failure", "input", "output", "provider_response", "charge_usd", "charge_basis", "stoppable", "stop_requested_at", "created_at", "started_at", "completed_at", "task_id", "metadata", "action", "result_status", "error", "runs", "result_url" ], "additionalProperties": false }, "EndpointVersionMismatchEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "endpoint_version_mismatch" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false }, "ConflictEncoded": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "conflict" ] }, "message": { "type": "string" }, "reason": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "control": { "anyOf": [ { "type": "string" }, { "type": "null" } ] }, "retry_after_ms": { "anyOf": [ { "anyOf": [ { "type": "integer" }, { "type": "null" } ] }, { "type": "null" } ] }, "details": { "anyOf": [ { "type": "object" }, { "type": "null" } ] } }, "required": [ "code", "message" ], "additionalProperties": false }, "request_id": { "type": "string" } }, "required": [ "error", "request_id" ], "additionalProperties": false } }, "securitySchemes": { "bearer": { "type": "http", "scheme": "Bearer" } } }, "security": [], "tags": [ { "name": "Solutions" }, { "name": "Endpoints" }, { "name": "Runs" }, { "name": "Balance" } ], "servers": [ { "url": "https://api.glasser.ai" } ] }