{ "components": { "schemas": { "GoogleTrendsTrendingListCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "google_trends.trending.list" ], "type": "string" }, "completed_at": { "anyOf": [ { "description": "When the source data was read and the job completed (ISO 8601 UTC). This is the observation time for the returned data, to the job's precision, not a per-item upstream timestamp. Null unless the job completed.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "job_id": { "format": "uuid", "type": "string" }, "outcome": { "description": "Truthful module completion detail; status is complete unless the module reports partial or incomplete output.", "type": "object" }, "platform": { "enum": [ "google_trends" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": { "items": { "additionalProperties": false, "properties": { "data": { "description": "Raw capability output. Its shape may evolve with the upstream source; the example is illustrative, not a compatibility guarantee.", "example": { "country": "US", "coverage": { "applied_hours": 24, "category_id": 0, "eligible_count": 2, "growth_basis": "relative_to_predicted_baseline", "include_ended": false, "observed_at": "2026-09-19T04:00:00Z", "requested_hours": 24, "returned_count": 2, "sort": "relevance", "source": "google_trends_trending_now", "source_url": "https://trends.google.com/trending?geo=US&hours=24", "truncated": false, "volume_basis": "bucketed_search_traffic" }, "execution": { "country_verified": true }, "hours": 24, "trends": [ { "active": true, "growth_percent": 50, "id": "mlb playoff picture|2026-09-19T03:40:00Z", "related_queries": [ "mlb playoff picture", "mlb wildcard standings", "al wild card standings" ], "search_volume": 1000, "started_at": "2026-09-19T03:40:00Z", "title": "mlb playoff picture" }, { "active": true, "growth_percent": 100, "id": "swimming|2026-09-19T03:30:00Z", "related_queries": [ "swimming" ], "search_volume": 200, "started_at": "2026-09-19T03:30:00Z", "title": "swimming" } ] } }, "error": { "type": "null" }, "index": { "const": 0, "type": "integer" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "index", "url", "data", "error" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "started_at": { "anyOf": [ { "description": "When the job began executing (ISO 8601 UTC), or null if it never ran.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "state": { "const": "completed", "type": "string" }, "stats": { "$ref": "#/components/schemas/JobStats" }, "success": { "const": true, "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "success", "started_at", "completed_at", "results", "billing", "stats", "outcome" ], "type": "object" }, "GoogleTrendsInterestByRegionInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "geo": { "description": "Country code; empty means worldwide. Assigned codes are validated before network access.", "pattern": "^$|^[A-Za-z]{2}$", "type": "string" }, "language": { "default": "en-US", "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "type": "string" }, "period": { "default": "today 12-m", "enum": [ "today 12-m", "today 5-y" ], "type": "string" }, "term": { "description": "Search term or verified Google topic ID beginning /m/ or /g/.", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "term" ], "type": "object" }, "JobPendingResponse": { "additionalProperties": false, "properties": { "capability": { "enum": [ "google_trends.interest.by_region", "google_trends.interest.over_time", "google_trends.topics.autocomplete", "google_trends.trending.daily", "google_trends.trending.list" ], "type": "string" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "google_trends" ], "type": "string" }, "poll_after_ms": { "description": "Wait at least this long before polling.", "minimum": 0, "type": "integer" }, "poll_url": { "description": "GET this URL with the same API key to read the job.", "format": "uri", "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "state": { "enum": [ "queued", "running", "retrying" ], "type": "string" } }, "required": [ "job_id", "request_id", "platform", "capability", "state" ], "type": "object" }, "GoogleTrendsTrendingDailyCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "google_trends.trending.daily" ], "type": "string" }, "completed_at": { "anyOf": [ { "description": "When the source data was read and the job completed (ISO 8601 UTC). This is the observation time for the returned data, to the job's precision, not a per-item upstream timestamp. Null unless the job completed.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "job_id": { "format": "uuid", "type": "string" }, "outcome": { "description": "Truthful module completion detail; status is complete unless the module reports partial or incomplete output.", "type": "object" }, "platform": { "enum": [ "google_trends" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": { "items": { "additionalProperties": false, "properties": { "data": { "description": "Raw capability output. Its shape may evolve with the upstream source; the example is illustrative, not a compatibility guarantee.", "example": { "country": "US", "coverage": { "item_count": 3, "observed_at": "2026-10-16T22:04:00Z", "order": "source", "region_basis": "requested_location", "source": "google_trends_daily_rss", "source_url": "https://trends.google.com/trending/rss?geo=US-CA", "traffic_basis": "approximate_traffic_band" }, "geo": "US-CA", "items": [ { "approx_traffic": "500+", "approx_traffic_min": 500, "news_items": [ { "picture_url": "https://encrypted-tbn3.gstatic.com/images?q=tbn:[redacted:token]", "source": "CNN", "title": "A super El Niño winter is coming and the first official forecast is in", "url": "https://www.cnn.com/2026/10/15/weather/winter-outlook-super-el-nino" }, { "picture_url": "https://encrypted-tbn3.gstatic.com/images?q=tbn:[redacted:token]", "source": "WKRC", "title": "Cincinnati winter forecast: What strong El Niño conditions signal", "url": "https://local12.com/weather/weather-articles/cincinnati-winter-forecast-what-strong-el-nino-conditions-signal-john-gumm-snowfall-temperatures" }, { "picture_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:[redacted:token]", "source": "KCCI", "title": "Looking ahead: Iowa's winter weather outlook", "url": "https://www.kcci.com/article/looking-ahead-iowas-winter-weather-outlook/74149316" } ], "picture_source": "CNN", "picture_url": "https://encrypted-tbn3.gstatic.com/images?q=tbn:[redacted:token]", "published_at": "2026-10-16T21:10:00Z", "title": "winter weather forecast" }, { "approx_traffic": "100+", "approx_traffic_min": 100, "news_items": [ { "picture_url": "https://encrypted-tbn1.gstatic.com/images?q=tbn:[redacted:token]", "source": "Politico", "title": "Microsoft’s president warns White House against skilled immigration crackdown", "url": "https://www.politico.com/news/2026/10/15/[redacted:token]" }, { "picture_url": "https://encrypted-tbn1.gstatic.com/images?q=tbn:[redacted:token]", "source": "CNBC", "title": "India calls JD Vance's comments about immigrants 'deeply offensive'", "url": "https://www.cnbc.com/2026/10/09/india-us-immigration-h1b-visa.html" }, { "picture_url": "https://encrypted-tbn1.gstatic.com/images?q=tbn:[redacted:token]", "source": "The Christian Science Monitor", "title": "Hopes and risks as US curbs flow of skilled foreign workers", "url": "https://www.csmonitor.com/USA/2026/1015/skilled-workers-visas-vance" } ], "picture_source": "Politico", "picture_url": "https://encrypted-tbn1.gstatic.com/images?q=tbn:[redacted:token]", "published_at": "2026-10-16T21:10:00Z", "title": "h-1b visa" }, { "approx_traffic": "100+", "approx_traffic_min": 100, "news_items": [ { "picture_url": "https://encrypted-tbn2.gstatic.com/images?q=tbn:[redacted:token]", "source": "Univision", "title": "La Guardia Costera de Estados Unidos rescató al menos a 16 personas y busca a más en las aguas frente a la costa de California", "url": "https://www.univision.com/noticias/inmigracion/[redacted:token]" }, { "picture_url": "https://encrypted-tbn2.gstatic.com/images?q=tbn:[redacted:token]", "source": "San Antonio Express-News", "title": "Guardia Costera de EEUU rescata a 16 personas tras llamada de auxilio en costa de Baja California", "url": "https://www.expressnews.com/news/world/article/[redacted:token].php" }, { "picture_url": "https://encrypted-tbn0.gstatic.com/images?q=tbn:[redacted:token]", "source": "San Diego Union-Tribune", "title": "La Guardia Costera rescató a 16 personas del mar frente a Ensenada y se reporta que aún hay más víctimas en el agua", "url": "https://www.sandiegouniontribune.com/2026/10/16/[redacted:token]/" } ], "picture_source": "Univision", "picture_url": "https://encrypted-tbn2.gstatic.com/images?q=tbn:[redacted:token]", "published_at": "2026-10-16T21:00:00Z", "title": "guardia costera" } ], "region": "CA" } }, "error": { "type": "null" }, "index": { "const": 0, "type": "integer" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "index", "url", "data", "error" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "started_at": { "anyOf": [ { "description": "When the job began executing (ISO 8601 UTC), or null if it never ran.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "state": { "const": "completed", "type": "string" }, "stats": { "$ref": "#/components/schemas/JobStats" }, "success": { "const": true, "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "success", "started_at", "completed_at", "results", "billing", "stats", "outcome" ], "type": "object" }, "JobBilling": { "additionalProperties": false, "properties": { "credits_charged": { "anyOf": [ { "description": "Actual credits charged, which may be a part of a credit such as 0.25. Null only when retained historical facts cannot establish the amount.", "minimum": 0, "type": "number" }, { "type": "null" } ] }, "credits_per_unit": { "anyOf": [ { "description": "Snapshotted price for one billed unit, which may be a part of a credit such as 0.25. Zero only for historical free work; null when unknown.", "minimum": 0, "type": "number" }, { "type": "null" } ] }, "model": { "enum": [ "per_request", "per_record", "free", "unknown" ], "type": "string" }, "pricing": { "additionalProperties": false, "properties": { "rule_id": { "anyOf": [ { "minLength": 1, "type": "string" }, { "type": "null" } ] }, "scope": { "anyOf": [ { "enum": [ "module", "platform", "capability" ], "type": "string" }, { "type": "null" } ] }, "source": { "enum": [ "manifest", "price_book" ], "type": "string" }, "version": { "anyOf": [ { "minimum": 1, "type": "integer" }, { "type": "null" } ] } }, "required": [ "source", "scope", "version", "rule_id" ], "type": "object" }, "settlement": { "description": "Why this job did or did not produce a credit debit. `cache_hit` means the same request was answered again from a recent result, and `credits_charged` is 0. A zero charge is not implicitly described as free.", "enum": [ "prepaid_credits", "included_subscription", "out_of_band_contract", "free", "cache_hit", "not_billable", "zero_charge_requires_review", "unknown" ], "type": "string" }, "units": { "anyOf": [ { "description": "Billed units under the stated model. Null when units do not apply or cannot be established.", "minimum": 0, "type": "integer" }, { "type": "null" } ] } }, "required": [ "model", "units", "credits_per_unit", "credits_charged", "settlement", "pricing" ], "type": "object" }, "GoogleTrendsTopicsAutocompleteCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "google_trends.topics.autocomplete" ], "type": "string" }, "completed_at": { "anyOf": [ { "description": "When the source data was read and the job completed (ISO 8601 UTC). This is the observation time for the returned data, to the job's precision, not a per-item upstream timestamp. Null unless the job completed.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "job_id": { "format": "uuid", "type": "string" }, "outcome": { "description": "Truthful module completion detail; status is complete unless the module reports partial or incomplete output.", "type": "object" }, "platform": { "enum": [ "google_trends" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": { "items": { "additionalProperties": false, "properties": { "data": { "description": "Raw capability output. Its shape may evolve with the upstream source; the example is illustrative, not a compatibility guarantee.", "example": { "language": "en-US", "query": "coffee", "results": [ { "title": "Coffee", "topic_id": "/m/02vqfm", "type": "Beverage" } ] } }, "error": { "type": "null" }, "index": { "const": 0, "type": "integer" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "index", "url", "data", "error" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "started_at": { "anyOf": [ { "description": "When the job began executing (ISO 8601 UTC), or null if it never ran.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "state": { "const": "completed", "type": "string" }, "stats": { "$ref": "#/components/schemas/JobStats" }, "success": { "const": true, "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "success", "started_at", "completed_at", "results", "billing", "stats", "outcome" ], "type": "object" }, "UnauthorizedError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "unauthorized", "type": "string" }, "message": { "enum": [ "authentication required", "invalid or revoked API key; check it under API keys in the console, sent as Authorization: Bearer ", "missing API key; send it as the header Authorization: Bearer " ], "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "GoogleTrendsInterestByRegionCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "google_trends.interest.by_region" ], "type": "string" }, "completed_at": { "anyOf": [ { "description": "When the source data was read and the job completed (ISO 8601 UTC). This is the observation time for the returned data, to the job's precision, not a per-item upstream timestamp. Null unless the job completed.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "job_id": { "format": "uuid", "type": "string" }, "outcome": { "description": "Truthful module completion detail; status is complete unless the module reports partial or incomplete output.", "type": "object" }, "platform": { "enum": [ "google_trends" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": { "items": { "additionalProperties": false, "properties": { "data": { "description": "Raw capability output. Its shape may evolve with the upstream source; the example is illustrative, not a compatibility guarantee.", "example": { "geo": "US", "language": "en-US", "period": "today 12-m", "results": [ { "geo_code": "US-WY", "geo_name": "Wyoming", "has_data": null, "value": 100 }, { "geo_code": "US-KS", "geo_name": "Kansas", "has_data": null, "value": 41 } ], "term": "coffee" } }, "error": { "type": "null" }, "index": { "const": 0, "type": "integer" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "index", "url", "data", "error" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "started_at": { "anyOf": [ { "description": "When the job began executing (ISO 8601 UTC), or null if it never ran.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "state": { "const": "completed", "type": "string" }, "stats": { "$ref": "#/components/schemas/JobStats" }, "success": { "const": true, "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "success", "started_at", "completed_at", "results", "billing", "stats", "outcome" ], "type": "object" }, "JobStats": { "additionalProperties": false, "properties": { "attempts": { "description": "Number of execution attempts made for the job.", "minimum": 0, "type": "integer" }, "duration_ms": { "anyOf": [ { "description": "Duration of the final execution attempt.", "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "failed": { "const": 0, "type": "integer" }, "passed": { "const": 1, "type": "integer" }, "processing_duration_ms": { "anyOf": [ { "description": "Total job processing time, including retries and retry backoff.", "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "queue_duration_ms": { "anyOf": [ { "description": "Time between job acceptance and the first execution attempt.", "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "run_duration_ms": { "anyOf": [ { "description": "Canonical run time from job acceptance to completion. Use this for customer-facing timing.", "minimum": 0, "type": "integer" }, { "type": "null" } ] }, "total": { "const": 1, "type": "integer" } }, "required": [ "total", "passed", "failed", "run_duration_ms", "duration_ms", "processing_duration_ms", "queue_duration_ms", "attempts" ], "type": "object" }, "UnavailableError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "temporarily_unavailable", "type": "string" }, "message": { "const": "this capability is temporarily unavailable; try again later or use another capability", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "InternalError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "internal_error", "type": "string" }, "message": { "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "CredentialsRequiredError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "credentials_required", "type": "string" }, "message": { "const": "this capability requires authentication credentials; save them via POST /credentials", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "GoogleTrendsTrendingListExecuteRequest": { "additionalProperties": false, "description": "Return Google Trending Now searches by country and time window, with categories, related queries and an optional category filter.", "example": { "capability": "google_trends.trending.list", "input": { "country": "US", "hours": 24, "limit": 25, "sort": "started_at" } }, "properties": { "capability": { "enum": [ "google_trends.trending.list" ], "type": "string" }, "input": { "$ref": "#/components/schemas/GoogleTrendsTrendingListInput" }, "max_credits": { "description": "Optional credit ceiling. The job is refused with `credit_limit_exceeded` before acceptance when its published price is higher. Takes precedence over the `X-Max-Credits` header.", "minimum": 1, "type": "integer" }, "network": { "$ref": "#/components/schemas/ExecuteNetwork" }, "timeout_ms": { "description": "Optional request timeout in milliseconds. Values above the capability timeout are rejected.", "maximum": 60000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "type": "object" }, "GoogleTrendsInterestOverTimeExecuteRequest": { "additionalProperties": false, "description": "Compare normalized search interest for one or two terms or topic IDs over a verified relative time window.", "example": { "capability": "google_trends.interest.over_time", "input": { "geo": "US", "language": "en-US", "period": "today 12-m", "terms": [ "coffee", "tea" ] } }, "properties": { "capability": { "enum": [ "google_trends.interest.over_time" ], "type": "string" }, "input": { "$ref": "#/components/schemas/GoogleTrendsInterestOverTimeInput" }, "max_credits": { "description": "Optional credit ceiling. The job is refused with `credit_limit_exceeded` before acceptance when its published price is higher. Takes precedence over the `X-Max-Credits` header.", "minimum": 1, "type": "integer" }, "network": { "$ref": "#/components/schemas/ExecuteNetwork" }, "timeout_ms": { "description": "Optional request timeout in milliseconds. Values above the capability timeout are rejected.", "maximum": 60000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "type": "object" }, "JobErrorObject": { "additionalProperties": false, "properties": { "code": { "description": "Machine-readable error code (e.g. forbidden, not_found, invalid_input, upstream_timeout, upstream_error).", "type": "string" }, "message": { "description": "Human-readable error description.", "type": "string" }, "reason": { "description": "A stable machine-readable reason when the code alone is not specific enough, for example country_unverified on a forbidden response where the requested country could not be verified. Present only for reviewed reasons; never a raw upstream diagnostic.", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "ValidationErrors": { "additionalProperties": false, "properties": { "error": { "description": "The standard error envelope, as on every other failure. Branch on `error.code`.", "properties": { "code": { "const": "invalid_input", "type": "string" }, "fields": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "description": "Failed fields and their messages.", "type": "object" }, "message": { "description": "One-line summary of the failed fields.", "type": "string" } }, "required": [ "code", "message", "fields" ], "type": "object" }, "errors": { "additionalProperties": { "items": { "type": "string" }, "type": "array" }, "description": "Retained for compatibility: the same field map as `error.fields`. New integrations should read `error`.", "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "errors", "error", "request_id" ], "type": "object" }, "QuotaError": { "oneOf": [ { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "account_inactive", "type": "string" }, "message": { "const": "an active paid account is required", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "quota_exhausted", "type": "string" }, "message": { "const": "request quota exhausted for current billing period", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "quota_exhausted", "type": "string" }, "message": { "const": "not enough credits for this request; buy credits at https://app.upscrape.com/app/billing to continue", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "account_inactive", "type": "string" }, "message": { "const": "this account is not active; buy credits at https://app.upscrape.com/app/billing to activate it, or contact support if it was suspended", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" } ] }, "JobFailedResponse": { "additionalProperties": false, "properties": { "capability": { "enum": [ "google_trends.interest.by_region", "google_trends.interest.over_time", "google_trends.topics.autocomplete", "google_trends.trending.daily", "google_trends.trending.list" ], "type": "string" }, "completed_at": { "anyOf": [ { "description": "When the source data was read and the job completed (ISO 8601 UTC). This is the observation time for the returned data, to the job's precision, not a per-item upstream timestamp. Null unless the job completed.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "error": { "$ref": "#/components/schemas/JobErrorObject" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "google_trends" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": { "type": "null" }, "started_at": { "anyOf": [ { "description": "When the job began executing (ISO 8601 UTC), or null if it never ran.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "state": { "const": "failed", "type": "string" }, "stats": { "type": "null" }, "success": { "const": false, "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "success", "error", "results", "stats", "started_at", "completed_at" ], "type": "object" }, "CreditLimitError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "credit_limit_exceeded", "type": "string" }, "message": { "const": "published job price exceeds the requested maximum credits", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "ExecuteNetwork": { "additionalProperties": false, "properties": { "session_id": { "description": "Optional explicit session identifier.", "minLength": 1, "type": "string" }, "session_key": { "description": "Optional stable key used to derive a reusable session.", "minLength": 1, "type": "string" }, "sticky": { "description": "Whether the request should reuse the resolved session.", "type": "boolean" } }, "type": "object" }, "ExecuteAcceptedResponse": { "additionalProperties": false, "properties": { "capability": { "enum": [ "google_trends.interest.by_region", "google_trends.interest.over_time", "google_trends.topics.autocomplete", "google_trends.trending.daily", "google_trends.trending.list" ], "type": "string" }, "coalesced": { "type": "boolean" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "google_trends" ], "type": "string" }, "poll_after_ms": { "description": "Wait at least this long before polling.", "minimum": 0, "type": "integer" }, "poll_url": { "description": "GET this URL with the same API key to read the job.", "format": "uri", "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "state": { "const": "queued", "type": "string" } }, "required": [ "job_id", "request_id", "platform", "capability", "state" ], "type": "object" }, "GoogleTrendsTrendingListInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "category_id": { "default": 0, "description": "Trending Now category ID; 0 includes all. Filters the complete fetched window before sorting and limiting. This is not an Explore category ID.", "enum": [ 0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 13, 14, 15, 16, 17, 18, 19, 20 ], "type": "integer" }, "country": { "description": "Assigned ISO 3166-1 alpha-2 country code, case-insensitive (for example US or IN); XK is accepted for Kosovo. Availability depends on Trending Now.", "pattern": "^[A-Za-z]{2}$", "type": "string" }, "hours": { "default": 24, "enum": [ 4, 24, 48, 168 ], "type": "integer" }, "include_ended": { "default": false, "type": "boolean" }, "limit": { "default": 100, "maximum": 500, "minimum": 1, "type": "integer" }, "sort": { "default": "relevance", "enum": [ "relevance", "title", "volume", "started_at" ], "type": "string" } }, "required": [ "country" ], "title": "Google Trends Trending Now input", "type": "object" }, "GoogleTrendsTrendingDailyExecuteRequest": { "additionalProperties": false, "description": "Google's daily trending searches for a country or region, with approximate traffic band, time and news links.", "example": { "capability": "google_trends.trending.daily", "input": { "country": "US", "region": "CA" } }, "properties": { "capability": { "enum": [ "google_trends.trending.daily" ], "type": "string" }, "input": { "$ref": "#/components/schemas/GoogleTrendsTrendingDailyInput" }, "max_credits": { "description": "Optional credit ceiling. The job is refused with `credit_limit_exceeded` before acceptance when its published price is higher. Takes precedence over the `X-Max-Credits` header.", "minimum": 1, "type": "integer" }, "network": { "$ref": "#/components/schemas/ExecuteNetwork" }, "timeout_ms": { "description": "Optional request timeout in milliseconds. Values above the capability timeout are rejected.", "maximum": 30000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "type": "object" }, "RateLimitError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "rate_limited", "type": "string" }, "message": { "const": "rate limit exceeded", "type": "string" }, "retry_after_ms": { "description": "Milliseconds until the rolling window resets enough to retry. The `retry-after` response header carries the same value rounded up to seconds.", "minimum": 0, "type": "integer" } }, "required": [ "code", "message", "retry_after_ms" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "ExecuteReplayResponse": { "additionalProperties": false, "description": "Replayed response matching the original job's current state (completed, failed, or pending).", "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "google_trends.interest.by_region", "google_trends.interest.over_time", "google_trends.topics.autocomplete", "google_trends.trending.daily", "google_trends.trending.list" ], "type": "string" }, "completed_at": { "anyOf": [ { "description": "When the source data was read and the job completed (ISO 8601 UTC). This is the observation time for the returned data, to the job's precision, not a per-item upstream timestamp. Null unless the job completed.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "error": {}, "idempotent_replay": { "const": true, "type": "boolean" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "google_trends" ], "type": "string" }, "poll_after_ms": { "minimum": 0, "type": "integer" }, "poll_url": { "format": "uri", "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": {}, "started_at": { "anyOf": [ { "description": "When the job began executing (ISO 8601 UTC), or null if it never ran.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "state": { "enum": [ "queued", "running", "retrying", "completed", "failed" ], "type": "string" }, "stats": {}, "success": { "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "idempotent_replay" ], "type": "object" }, "NotFoundError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "not_found", "type": "string" }, "message": { "enum": [ "job not found", "monitor not found", "monitors are not available for this account" ], "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "GoogleTrendsInterestByRegionExecuteRequest": { "additionalProperties": false, "description": "Return regional relative interest for a term or topic ID; missing data remains distinct from zero.", "example": { "capability": "google_trends.interest.by_region", "input": { "geo": "US", "language": "en-US", "period": "today 12-m", "term": "coffee" } }, "properties": { "capability": { "enum": [ "google_trends.interest.by_region" ], "type": "string" }, "input": { "$ref": "#/components/schemas/GoogleTrendsInterestByRegionInput" }, "max_credits": { "description": "Optional credit ceiling. The job is refused with `credit_limit_exceeded` before acceptance when its published price is higher. Takes precedence over the `X-Max-Credits` header.", "minimum": 1, "type": "integer" }, "network": { "$ref": "#/components/schemas/ExecuteNetwork" }, "timeout_ms": { "description": "Optional request timeout in milliseconds. Values above the capability timeout are rejected.", "maximum": 60000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "type": "object" }, "GoogleTrendsTrendingDailyInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "country": { "description": "ISO 3166-1 alpha-2 country code, case-insensitive (for example US or IN). The daily feed serves about half of all countries; others return invalid_input naming country.", "pattern": "^[A-Za-z]{2}$", "type": "string" }, "region": { "description": "Optional subdivision inside country, as its ISO 3166-2 code (US-CA) or the part after the dash (CA), case-insensitive. Only subdivisions the feed serves are accepted; others return invalid_input naming region and never fall back to the whole country. Omit for the whole country.", "pattern": "^(?:[A-Za-z]{2}-)?[A-Za-z0-9]{1,3}$", "type": "string" } }, "required": [ "country" ], "title": "Google Trends daily search trends input", "type": "object" }, "IdempotencyConflictError": { "additionalProperties": false, "properties": { "error": { "additionalProperties": false, "properties": { "code": { "const": "idempotency_conflict", "type": "string" }, "message": { "const": "idempotency key has already been used for a different request", "type": "string" } }, "required": [ "code", "message" ], "type": "object" }, "request_id": { "description": "Safe Upscrape HTTP request identifier, also returned in the x-request-id header. For accepted jobs, job_id is the durable execution identifier.", "minLength": 1, "type": "string" } }, "required": [ "error", "request_id" ], "type": "object" }, "GoogleTrendsTopicsAutocompleteExecuteRequest": { "additionalProperties": false, "description": "Find Google topic IDs, titles and types matching a query for use in interest and related-query requests.", "example": { "capability": "google_trends.topics.autocomplete", "input": { "language": "en-US", "limit": 10, "query": "coffee" } }, "properties": { "capability": { "enum": [ "google_trends.topics.autocomplete" ], "type": "string" }, "input": { "$ref": "#/components/schemas/GoogleTrendsTopicsAutocompleteInput" }, "max_credits": { "description": "Optional credit ceiling. The job is refused with `credit_limit_exceeded` before acceptance when its published price is higher. Takes precedence over the `X-Max-Credits` header.", "minimum": 1, "type": "integer" }, "network": { "$ref": "#/components/schemas/ExecuteNetwork" }, "timeout_ms": { "description": "Optional request timeout in milliseconds. Values above the capability timeout are rejected.", "maximum": 60000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "type": "object" }, "GoogleTrendsInterestOverTimeInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "geo": { "description": "Country code; empty means worldwide. Assigned codes are validated before network access.", "pattern": "^$|^[A-Za-z]{2}$", "type": "string" }, "language": { "default": "en-US", "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "type": "string" }, "period": { "default": "today 12-m", "enum": [ "today 12-m", "today 5-y" ], "type": "string" }, "terms": { "items": { "description": "Search term or verified Google topic ID beginning /m/ or /g/.", "maxLength": 200, "minLength": 1, "type": "string" }, "maxItems": 2, "minItems": 1, "type": "array", "uniqueItems": true } }, "required": [ "terms" ], "type": "object" }, "GoogleTrendsInterestOverTimeCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "google_trends.interest.over_time" ], "type": "string" }, "completed_at": { "anyOf": [ { "description": "When the source data was read and the job completed (ISO 8601 UTC). This is the observation time for the returned data, to the job's precision, not a per-item upstream timestamp. Null unless the job completed.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "job_id": { "format": "uuid", "type": "string" }, "outcome": { "description": "Truthful module completion detail; status is complete unless the module reports partial or incomplete output.", "type": "object" }, "platform": { "enum": [ "google_trends" ], "type": "string" }, "request_id": { "format": "uuid", "type": "string" }, "results": { "items": { "additionalProperties": false, "properties": { "data": { "description": "Raw capability output. Its shape may evolve with the upstream source; the example is illustrative, not a compatibility guarantee.", "example": { "geo": "US", "language": "en-US", "period": "today 12-m", "results": [ { "formatted_time": "", "has_data": [ true, true ], "is_partial": null, "time": "1759017600", "values": [ 70, 33 ] }, { "formatted_time": "", "has_data": [ true, true ], "is_partial": null, "time": "1759622400", "values": [ 61, 33 ] }, { "formatted_time": "", "has_data": [ true, true ], "is_partial": null, "time": "1760227200", "values": [ 61, 33 ] } ], "terms": [ "coffee", "tea" ] } }, "error": { "type": "null" }, "index": { "const": 0, "type": "integer" }, "url": { "anyOf": [ { "type": "string" }, { "type": "null" } ] } }, "required": [ "index", "url", "data", "error" ], "type": "object" }, "maxItems": 1, "minItems": 1, "type": "array" }, "started_at": { "anyOf": [ { "description": "When the job began executing (ISO 8601 UTC), or null if it never ran.", "format": "date-time", "type": "string" }, { "type": "null" } ] }, "state": { "const": "completed", "type": "string" }, "stats": { "$ref": "#/components/schemas/JobStats" }, "success": { "const": true, "type": "boolean" } }, "required": [ "job_id", "request_id", "platform", "capability", "state", "success", "started_at", "completed_at", "results", "billing", "stats", "outcome" ], "type": "object" }, "GoogleTrendsTopicsAutocompleteInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "language": { "default": "en-US", "pattern": "^[a-z]{2}(-[A-Z]{2})?$", "type": "string" }, "limit": { "default": 10, "maximum": 25, "minimum": 1, "type": "integer" }, "query": { "description": "Search term or verified Google topic ID beginning /m/ or /g/.", "maxLength": 200, "minLength": 1, "type": "string" } }, "required": [ "query" ], "type": "object" } }, "securitySchemes": { "BearerAuth": { "bearerFormat": "API Key", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Get Google Trends data as JSON: how interest in a search term changes over time, where it is searched most, and what is trending in a country right now. No browser and no scraping code.\nThis spec includes only the live `Google Trends` capabilities exposed by Upscrape.\nExecution uses the generic `POST /execute` endpoint and job polling uses `GET /jobs/{id}`.\nSupported capabilities: `google_trends.interest.by_region`, `google_trends.interest.over_time`, `google_trends.topics.autocomplete`, `google_trends.trending.daily`, `google_trends.trending.list`\n## Rate limiting\n\nRequests are rate-limited per API key at **1200 requests per minute** on a rolling window. Every response includes `x-ratelimit-limit`, `x-ratelimit-remaining`, and `x-ratelimit-reset` (Unix ms) headers so clients can self-pace. When the limit is exceeded the API returns `429` with a `rate_limited` error body and a `retry-after` header in seconds plus a `retry_after_ms` field on the body for finer-grained backoff.", "title": "Google Trends API", "version": "1.0.0" }, "jsonSchemaDialect": "https://json-schema.org/draft/2020-12/schema", "openapi": "3.1.0", "paths": { "/execute": { "post": { "description": "All executions are asynchronous. Submit a capability-specific payload to `POST /execute`, then poll the returned `job_id`.", "operationId": "google_trends_execute", "parameters": [ { "description": "Optional idempotency key. Reusing the same key with the same request replays the original job.", "in": "header", "name": "Idempotency-Key", "required": false, "schema": { "maxLength": 255, "type": "string" } }, { "description": "Optional credit ceiling for this job, as a positive integer. The request is refused with `422 credit_limit_exceeded` before acceptance when the published price for the submitted input is higher. The body field `max_credits` takes precedence when both are sent. It never changes the price.", "in": "header", "name": "X-Max-Credits", "required": false, "schema": { "minimum": 1, "type": "integer" } }, { "description": "Request synchronous completion. Use `wait=N` to hold the connection up to N seconds (max 30). If the job completes within the window, the response is `200` with full results (same shape as `GET /jobs/{id}`). If not, the response is the normal `202` with a `job_id` for polling. Omit this header for default asynchronous behavior.", "examples": { "wait30": { "summary": "Wait up to 30 seconds", "value": "wait=30" }, "wait5": { "summary": "Wait up to 5 seconds", "value": "wait=5" } }, "in": "header", "name": "Prefer", "required": false, "schema": { "example": "wait=30", "type": "string" } } ], "requestBody": { "content": { "application/json": { "example": { "capability": "google_trends.interest.by_region", "input": { "geo": "US", "language": "en-US", "period": "today 12-m", "term": "coffee" } }, "schema": { "discriminator": { "mapping": { "google_trends.interest.by_region": "#/components/schemas/GoogleTrendsInterestByRegionExecuteRequest", "google_trends.interest.over_time": "#/components/schemas/GoogleTrendsInterestOverTimeExecuteRequest", "google_trends.topics.autocomplete": "#/components/schemas/GoogleTrendsTopicsAutocompleteExecuteRequest", "google_trends.trending.daily": "#/components/schemas/GoogleTrendsTrendingDailyExecuteRequest", "google_trends.trending.list": "#/components/schemas/GoogleTrendsTrendingListExecuteRequest" }, "propertyName": "capability" }, "oneOf": [ { "$ref": "#/components/schemas/GoogleTrendsInterestByRegionExecuteRequest" }, { "$ref": "#/components/schemas/GoogleTrendsInterestOverTimeExecuteRequest" }, { "$ref": "#/components/schemas/GoogleTrendsTopicsAutocompleteExecuteRequest" }, { "$ref": "#/components/schemas/GoogleTrendsTrendingDailyExecuteRequest" }, { "$ref": "#/components/schemas/GoogleTrendsTrendingListExecuteRequest" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/GoogleTrendsInterestByRegionCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsInterestOverTimeCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsTopicsAutocompleteCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsTrendingDailyCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsTrendingListCompletedJob" }, { "$ref": "#/components/schemas/ExecuteReplayResponse" }, { "$ref": "#/components/schemas/JobFailedResponse" } ] } } }, "description": "Job completed within the `Prefer: wait` window, or existing job replayed via idempotency key.", "headers": { "Preference-Applied": { "description": "Present when the server honored the `Prefer: wait` preference.", "schema": { "example": "wait=30", "type": "string" } }, "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "202": { "content": { "application/json": { "example": { "capability": "google_trends.interest.by_region", "job_id": "00000000-0000-0000-0000-000000000001", "platform": "google_trends", "poll_after_ms": 2000, "poll_url": "https://data.upscrape.com/jobs/00000000-0000-0000-0000-000000000001", "request_id": "00000000-0000-0000-0000-000000000001", "state": "queued" }, "schema": { "$ref": "#/components/schemas/ExecuteAcceptedResponse" } } }, "description": "Job accepted and queued, or attached to an identical active keyless request.", "headers": { "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } }, "description": "Unauthorized" }, "402": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QuotaError" } } }, "description": "The authenticated account cannot execute the request." }, "403": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobFailedResponse" } } }, "description": "The requested public data is unavailable or access is denied. Confirmed account privacy and sign-in requirements include a safe reason." }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobFailedResponse" } } }, "description": "The upstream source confirms that the requested resource was not found. The response retains the job identity." }, "409": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/IdempotencyConflictError" } } }, "description": "Idempotency conflict" }, "422": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/ValidationErrors" }, { "$ref": "#/components/schemas/CredentialsRequiredError" }, { "$ref": "#/components/schemas/CreditLimitError" } ] } } }, "description": "The request body failed validation." }, "424": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JobFailedResponse" } } }, "description": "A durable job reached a terminal upstream dependency failure within the Prefer wait window. The body retains job_id and request_id for diagnosis." }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "rate limit exceeded", "retry_after_ms": 4200 }, "request_id": "safe-http-request-id" }, "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-API-key rate limit has been exceeded. Clients should back off until `retry_after_ms` has elapsed (or `retry-after` seconds).", "headers": { "retry-after": { "description": "Seconds until the client may retry (ceiling of `retry_after_ms`).", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "500": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InternalError" } } }, "description": "Unexpected server error" }, "503": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnavailableError" } } }, "description": "The capability cannot be served right now. Do not retry immediately; try again later." } }, "security": [ { "BearerAuth": [] } ], "summary": "Queue a Google Trends capability run", "tags": [ "Execution" ] } }, "/jobs/{id}": { "get": { "description": "Get job status and result", "operationId": "google_trends_getJob", "parameters": [ { "description": "The job ID returned by `POST /execute`.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/GoogleTrendsInterestByRegionCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsInterestOverTimeCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsTopicsAutocompleteCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsTrendingDailyCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsTrendingListCompletedJob" }, { "$ref": "#/components/schemas/JobFailedResponse" } ] } } }, "description": "Completed or terminal job state.", "headers": { "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "202": { "content": { "application/json": { "example": { "capability": "google_trends.interest.by_region", "job_id": "00000000-0000-0000-0000-000000000001", "platform": "google_trends", "poll_after_ms": 2000, "poll_url": "https://data.upscrape.com/jobs/00000000-0000-0000-0000-000000000001", "request_id": "00000000-0000-0000-0000-000000000001", "state": "running" }, "schema": { "$ref": "#/components/schemas/JobPendingResponse" } } }, "description": "Job is still queued, running, or retrying.", "headers": { "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } }, "description": "Job not found" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "rate limit exceeded", "retry_after_ms": 4200 }, "request_id": "safe-http-request-id" }, "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-API-key rate limit has been exceeded. Clients should back off until `retry_after_ms` has elapsed (or `retry-after` seconds).", "headers": { "retry-after": { "description": "Seconds until the client may retry (ceiling of `retry_after_ms`).", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Poll a Google Trends job", "tags": [ "Jobs" ] } }, "/jobs/{id}/result": { "get": { "description": "Backward-compatible alias for `/jobs/{id}`.", "operationId": "google_trends_getJobResult", "parameters": [ { "description": "The job ID returned by `POST /execute`.", "in": "path", "name": "id", "required": true, "schema": { "format": "uuid", "type": "string" } } ], "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/GoogleTrendsInterestByRegionCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsInterestOverTimeCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsTopicsAutocompleteCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsTrendingDailyCompletedJob" }, { "$ref": "#/components/schemas/GoogleTrendsTrendingListCompletedJob" }, { "$ref": "#/components/schemas/JobFailedResponse" } ] } } }, "description": "Completed or terminal job state.", "headers": { "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "202": { "content": { "application/json": { "example": { "capability": "google_trends.interest.by_region", "job_id": "00000000-0000-0000-0000-000000000001", "platform": "google_trends", "poll_after_ms": 2000, "poll_url": "https://data.upscrape.com/jobs/00000000-0000-0000-0000-000000000001", "request_id": "00000000-0000-0000-0000-000000000001", "state": "running" }, "schema": { "$ref": "#/components/schemas/JobPendingResponse" } } }, "description": "Job is still queued, running, or retrying.", "headers": { "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } }, "401": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnauthorizedError" } } }, "description": "Unauthorized" }, "404": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NotFoundError" } } }, "description": "Job not found" }, "429": { "content": { "application/json": { "example": { "error": { "code": "rate_limited", "message": "rate limit exceeded", "retry_after_ms": 4200 }, "request_id": "safe-http-request-id" }, "schema": { "$ref": "#/components/schemas/RateLimitError" } } }, "description": "The per-API-key rate limit has been exceeded. Clients should back off until `retry_after_ms` has elapsed (or `retry-after` seconds).", "headers": { "retry-after": { "description": "Seconds until the client may retry (ceiling of `retry_after_ms`).", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-limit": { "description": "Per-API-key request ceiling over the rolling window.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-remaining": { "description": "Requests remaining in the current window before throttling.", "schema": { "minimum": 0, "type": "integer" } }, "x-ratelimit-reset": { "description": "Unix epoch milliseconds at which the current window resets.", "schema": { "minimum": 0, "type": "integer" } } } } }, "security": [ { "BearerAuth": [] } ], "summary": "Poll a Google Trends job", "tags": [ "Jobs" ] } } }, "servers": [ { "url": "https://data.upscrape.com" } ], "tags": [ { "description": "Submit asynchronous capability runs.", "name": "Execution" }, { "description": "Poll queued jobs for status and results.", "name": "Jobs" } ] }