{ "components": { "schemas": { "RedfinSearchListingsCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "redfin.search.listings" ], "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": [ "redfin" ], "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": { "end_page": 1, "has_more": true, "listings": [ { "address": "1120 8th Ave #1603, Seattle, WA 98101", "area_sqft": 1050, "baths": 2, "beds": 2, "collected_at": "2026-10-14T05:00:00Z", "currency": "USD", "page": 1, "position": 1, "price": 526500, "property_id": "14602", "status": "Active", "title": "1120 8th Ave #1603", "url": "https://www.redfin.com/WA/Seattle/1120-8th-Ave-98101/unit-1603/home/14602" }, { "address": "1624 N 46th St, Seattle, WA 98103", "area_sqft": 2610, "baths": 2, "beds": 5, "collected_at": "2026-10-14T05:00:00Z", "currency": "USD", "page": 1, "position": 2, "price": 1199950, "property_id": "118803", "status": "Coming Soon", "title": "1624 N 46th St", "url": "https://www.redfin.com/WA/Seattle/1624-N-46th-St-98103/home/118803" } ], "next_page": 2, "pages_fetched": 1, "region_id": 16163, "region_type": 6, "start_page": 1, "total_count": 2 } }, "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" }, "RedfinSearchListingsInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "max_pages": { "maximum": 10, "minimum": 1, "type": "integer" }, "page": { "maximum": 50, "minimum": 1, "type": "integer" }, "query": { "description": "Optional human label echoed back in the output.", "maxLength": 240, "pattern": "\\S", "type": "string" }, "region_id": { "description": "Resolved Redfin region id (for example 16163 for Seattle, WA). Redfin's map-search route rejects a free-text location.", "minimum": 1, "type": "integer" }, "region_type": { "default": 6, "description": "Redfin region type; 6 is a city. Defaults to 6.", "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "region_id" ], "title": "Redfin.search.listings", "type": "object" }, "JobPendingResponse": { "additionalProperties": false, "properties": { "capability": { "enum": [ "redfin.agent.profile", "redfin.listings.for_rent", "redfin.listings.sold", "redfin.market.trends", "redfin.property.get", "redfin.search.listings" ], "type": "string" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "redfin" ], "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" }, "RedfinSearchListingsExecuteRequest": { "additionalProperties": false, "description": "Read Redfin's public map-search feed for a resolved region and return normalized for-sale listing cards with a bounded page summary.", "example": { "capability": "redfin.search.listings", "input": { "max_pages": 1, "page": 1, "query": "Seattle WA homes for sale", "region_id": 16163, "region_type": 6 } }, "properties": { "capability": { "enum": [ "redfin.search.listings" ], "type": "string" }, "input": { "$ref": "#/components/schemas/RedfinSearchListingsInput" }, "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": 45000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "type": "object" }, "RedfinAgentProfileInput": { "additionalProperties": false, "properties": { "profile_url": { "maxLength": 2048, "pattern": "^https://([A-Za-z0-9-]+\\.)*redfin\\.com/(real-estate-agents|partner-agent)/", "type": "string" } }, "required": [ "profile_url" ], "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" }, "RedfinMarketTrendsExecuteRequest": { "additionalProperties": false, "description": "Read bounded regional median-sale-price trends from five verified Redfin Data Center CSV downloads, with explicit dataset and source period metadata.", "example": { "capability": "redfin.market.trends", "input": { "limit": 12, "metric": "median_sale_price", "region": "Seattle, WA" } }, "properties": { "capability": { "enum": [ "redfin.market.trends" ], "type": "string" }, "input": { "$ref": "#/components/schemas/RedfinMarketTrendsInput" }, "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": 45000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "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" }, "RedfinMarketTrendsCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "redfin.market.trends" ], "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": [ "redfin" ], "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": { "dataset": "monthly_top_50_cities", "metric": "median_sale_price", "property_type": "aggregate", "region": "Seattle, WA", "region_id": "16163", "rows": [ { "change_pct": -0.16, "metrics": { "ACTIVE LISTINGS": 5395, "ACTIVE LISTINGS YOY (%)": 0.73, "AVERAGE SALE TO LIST RATIO (%)": 100.19, "AVERAGE SALE TO LIST RATIO YOY (PPTS)": -0.19, "HOMES SOLD": 2398, "HOMES SOLD YOY (%)": -6.08, "INVENTORY": 2387, "INVENTORY YOY (%)": 12.89, "MEDIAN DAYS ON MARKET (DAYS)": 12, "MEDIAN DAYS ON MARKET YOY (%)": 201.48, "MEDIAN NEW LISTING PRICE ($)": 841892, "MEDIAN NEW LISTING PRICE PER SQ.FT. ($)": 557.21, "MEDIAN NEW LISTING PRICE PER SQ.FT. YOY (%)": -2.2, "MEDIAN NEW LISTING PRICE YOY (%)": -2.67, "MEDIAN SALE PRICE NSA ($)": 898550, "MEDIAN SALE PRICE NSA YOY (%)": -0.16, "MEDIAN SALE PRICE PER SQ.FT. ($)": 560.93, "MEDIAN SALE PRICE PER SQ.FT. YOY (%)": -3.06, "MONTHS OF SUPPLY": 3.1, "MONTHS OF SUPPLY YOY (%)": 51.28, "NEW LISTINGS": 3362, "NEW LISTINGS YOY (%)": -7.79, "PENDING SALES": 2230, "PENDING SALES YOY (%)": -15.18, "PERCENT OFF MARKET IN TWO WEEKS (%)": 52.63, "PERCENT OFF MARKET IN TWO WEEKS YOY (PPTS)": -0.51, "REGION ID": 16163, "SHARE SOLD ABOVE ORIGINAL LIST (%)": 26.28, "SHARE SOLD ABOVE ORIGINAL LIST YOY (PPTS)": -0.24 }, "period_end": "2026-07-31", "period_start": "2026-05-01", "region": "Seattle, WA", "value": 898550 }, { "change_pct": -2.21, "metrics": { "ACTIVE LISTINGS": 5344, "ACTIVE LISTINGS YOY (%)": 0.17, "AVERAGE SALE TO LIST RATIO (%)": 100.57, "AVERAGE SALE TO LIST RATIO YOY (PPTS)": -0.63, "HOMES SOLD": 2485, "HOMES SOLD YOY (%)": -3.46, "INVENTORY": 2225, "INVENTORY YOY (%)": 2.3, "MEDIAN DAYS ON MARKET (DAYS)": 11, "MEDIAN DAYS ON MARKET YOY (%)": 400, "MEDIAN NEW LISTING PRICE ($)": 850000, "MEDIAN NEW LISTING PRICE PER SQ.FT. ($)": 565.16, "MEDIAN NEW LISTING PRICE PER SQ.FT. YOY (%)": -1.44, "MEDIAN NEW LISTING PRICE YOY (%)": 0, "MEDIAN SALE PRICE NSA ($)": 889925, "MEDIAN SALE PRICE NSA YOY (%)": -2.21, "MEDIAN SALE PRICE PER SQ.FT. ($)": 566.92, "MEDIAN SALE PRICE PER SQ.FT. YOY (%)": -3.92, "MONTHS OF SUPPLY": 2.7, "MONTHS OF SUPPLY YOY (%)": 15.28, "NEW LISTINGS": 3645, "NEW LISTINGS YOY (%)": -7.04, "PENDING SALES": 2493, "PENDING SALES YOY (%)": -7.08, "PERCENT OFF MARKET IN TWO WEEKS (%)": 55.35, "PERCENT OFF MARKET IN TWO WEEKS YOY (PPTS)": -4.21, "REGION ID": 16163, "SHARE SOLD ABOVE ORIGINAL LIST (%)": 28.49, "SHARE SOLD ABOVE ORIGINAL LIST YOY (PPTS)": -2.74 }, "period_end": "2026-06-30", "period_start": "2026-04-01", "region": "Seattle, WA", "value": 889925 }, { "change_pct": -2.22, "metrics": { "ACTIVE LISTINGS": 5228, "ACTIVE LISTINGS YOY (%)": 1.61, "AVERAGE SALE TO LIST RATIO (%)": 100.92, "AVERAGE SALE TO LIST RATIO YOY (PPTS)": -0.6, "HOMES SOLD": 2406, "HOMES SOLD YOY (%)": -1.96, "INVENTORY": 2226, "INVENTORY YOY (%)": 2.06, "MEDIAN DAYS ON MARKET (DAYS)": 10, "MEDIAN DAYS ON MARKET YOY (%)": 250, "MEDIAN NEW LISTING PRICE ($)": 849000, "MEDIAN NEW LISTING PRICE PER SQ.FT. ($)": 565.84, "MEDIAN NEW LISTING PRICE PER SQ.FT. YOY (%)": -1.81, "MEDIAN NEW LISTING PRICE YOY (%)": -0.12, "MEDIAN SALE PRICE NSA ($)": 880000, "MEDIAN SALE PRICE NSA YOY (%)": -2.22, "MEDIAN SALE PRICE PER SQ.FT. ($)": 566.19, "MEDIAN SALE PRICE PER SQ.FT. YOY (%)": -3.28, "MONTHS OF SUPPLY": 2.8, "MONTHS OF SUPPLY YOY (%)": 11.17, "NEW LISTINGS": 3698, "NEW LISTINGS YOY (%)": -5.78, "PENDING SALES": 2554, "PENDING SALES YOY (%)": -3.84, "PERCENT OFF MARKET IN TWO WEEKS (%)": 56.77, "PERCENT OFF MARKET IN TWO WEEKS YOY (PPTS)": -6.63, "REGION ID": 16163, "SHARE SOLD ABOVE ORIGINAL LIST (%)": 29.93, "SHARE SOLD ABOVE ORIGINAL LIST YOY (PPTS)": -1.98 }, "period_end": "2026-05-31", "period_start": "2026-03-01", "region": "Seattle, WA", "value": 880000 } ], "source": "Redfin Data Center S3 housing_market/monthly/top_50_cities.csv" } }, "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" }, "RedfinPropertyGetCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "redfin.property.get" ], "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": [ "redfin" ], "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": { "address": "130 29th Ave, Seattle, WA 98122", "area_sqft": 3200, "baths": 2, "beds": 4, "canonical": "https://www.redfin.com/WA/Seattle/130-29th-Ave-98122/home/148583", "city": "Seattle", "collected_at": "2026-10-15T06:03:37Z", "currency": "USD", "image_urls": [ "https://ssl.cdn-redfin.com/photo/1/mbpaddedwide/332/genMid.2567332_1.jpg", "https://ssl.cdn-redfin.com/photo/1/mbpaddedwide/332/genMid.2567332_1_1.jpg", "https://ssl.cdn-redfin.com/photo/1/mbpaddedwide/332/genMid.2567332_2_1.jpg" ], "price": 1018000, "property_id": "148583", "state": "WA", "title": "130 29th Ave, Seattle, WA 98122 - 4 beds/2 baths", "updated_at": "2026-10-15T06:03:37Z", "url": "https://www.redfin.com/WA/Seattle/130-29th-Ave-98122/home/148583", "zip": "98122" } }, "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" }, "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" }, "RedfinListingsSoldInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "max_pages": { "maximum": 10, "minimum": 1, "type": "integer" }, "page": { "maximum": 50, "minimum": 1, "type": "integer" }, "region_id": { "description": "Resolved Redfin region id (for example 16163 for the Seattle, WA city region). Redfin's map-search route rejects a free-text location.", "minimum": 1, "type": "integer" }, "region_type": { "default": 6, "description": "Redfin region type; 6 is a city. Defaults to 6.", "maximum": 100, "minimum": 1, "type": "integer" }, "sold_within_days": { "default": 90, "description": "Recency window for recently sold homes. Redfin honours these discrete buckets only.", "enum": [ 30, 90, 180, 365, 730, 1095 ], "type": "integer" } }, "required": [ "region_id" ], "title": "Redfin.listings.sold", "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" }, "RedfinListingsForRentCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "redfin.listings.for_rent" ], "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": [ "redfin" ], "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": { "end_page": 1, "has_more": true, "listings": [ { "address": "125 SW 112th St, Seattle, WA 98146", "area_sqft": 500, "baths": 1, "beds": 2, "currency": "USD", "id": "167200636", "page": 1, "position": 1, "rent": 2062, "status": "For Rent", "title": "Latitude 112", "url": "https://www.redfin.com/WA/Seattle/Latitude-112/apartment/167200636" }, { "address": "2227 Yale Ave E, Seattle, WA 98102", "area_sqft": 282, "baths": 1, "beds": 2, "currency": "USD", "id": "194270748", "page": 1, "position": 2, "rent": 1260, "status": "For Rent", "title": "Lakeview Apartments", "url": "https://www.redfin.com/WA/Seattle/Lakeview-Apartments/apartment/194270748" } ], "matched_count": 2986, "next_page": 2, "pages_fetched": 1, "query": "Seattle WA rentals", "region_id": 16163, "region_type": 6, "start_page": 1, "total_count": 2 } }, "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" }, "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" }, "RedfinListingsSoldExecuteRequest": { "additionalProperties": false, "description": "Find recently sold Redfin homes by region ID and sale window, with sold prices, dates, property details and bounded pagination.", "example": { "capability": "redfin.listings.sold", "input": { "max_pages": 1, "page": 1, "region_id": 16163, "region_type": 6, "sold_within_days": 90 } }, "properties": { "capability": { "enum": [ "redfin.listings.sold" ], "type": "string" }, "input": { "$ref": "#/components/schemas/RedfinListingsSoldInput" }, "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": 45000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "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" } ] }, "RedfinAgentProfileCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "redfin.agent.profile" ], "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": [ "redfin" ], "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": { "rating": 4.9, "review_count": 178 } }, "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" }, "JobFailedResponse": { "additionalProperties": false, "properties": { "capability": { "enum": [ "redfin.agent.profile", "redfin.listings.for_rent", "redfin.listings.sold", "redfin.market.trends", "redfin.property.get", "redfin.search.listings" ], "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": [ "redfin" ], "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" }, "RedfinMarketTrendsInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "dataset": { "default": "monthly_top_50_cities", "description": "One explicitly verified Redfin Data Center download. The default city file uses rolling three-month windows; monthly metro, state and country files use calendar months; the weekly metro file uses a trailing four-week window. Coverage is limited to the named source file.", "enum": [ "monthly_top_50_cities", "monthly_top_50_metros", "monthly_all_states", "monthly_country", "weekly_top_50_metros" ], "type": "string" }, "end_date": { "description": "Optional inclusive period end in YYYY-MM-DD format.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "type": "string" }, "limit": { "default": 12, "description": "Maximum matching rows to return from the selected download.", "maximum": 1000, "minimum": 1, "type": "integer" }, "metric": { "default": "median_sale_price", "description": "Normalized market metric returned in each row value.", "enum": [ "median_sale_price" ], "type": "string" }, "property_type": { "default": "aggregate", "description": "These five aggregate source files do not contain a property-type dimension. Segmented property types require separate source qualification.", "enum": [ "aggregate" ], "type": "string" }, "region": { "description": "Exact Redfin Data Center region name, for example Seattle, WA.", "maxLength": 160, "pattern": "\\S", "type": "string" }, "start_date": { "description": "Optional inclusive period start in YYYY-MM-DD format.", "pattern": "^[0-9]{4}-[0-9]{2}-[0-9]{2}$", "type": "string" } }, "required": [ "region" ], "title": "Redfin.market.trends", "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" }, "RedfinAgentProfileExecuteRequest": { "additionalProperties": false, "description": "Read public Redfin agent identity and professional aggregates, excluding direct contacts, reviewer identities and lead destinations.", "example": { "capability": "redfin.agent.profile", "input": { "profile_url": "https://www.redfin.com/real-estate-agents/chandra-gordon" } }, "properties": { "capability": { "enum": [ "redfin.agent.profile" ], "type": "string" }, "input": { "$ref": "#/components/schemas/RedfinAgentProfileInput" }, "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": 45000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "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": [ "redfin.agent.profile", "redfin.listings.for_rent", "redfin.listings.sold", "redfin.market.trends", "redfin.property.get", "redfin.search.listings" ], "type": "string" }, "coalesced": { "type": "boolean" }, "job_id": { "format": "uuid", "type": "string" }, "platform": { "enum": [ "redfin" ], "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" }, "RedfinListingsForRentInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "max_pages": { "maximum": 10, "minimum": 1, "type": "integer" }, "max_rent": { "minimum": 0, "type": "integer" }, "min_beds": { "minimum": 0, "type": "integer" }, "min_rent": { "minimum": 0, "type": "integer" }, "page": { "maximum": 50, "minimum": 1, "type": "integer" }, "query": { "description": "Optional human label echoed back in the output; it does not resolve a location.", "maxLength": 200, "pattern": "\\S", "type": "string" }, "region_id": { "description": "Resolved Redfin region id (for example 16163 for the Seattle, WA city region). Redfin's rental search route rejects a free-text location.", "minimum": 1, "type": "integer" }, "region_type": { "default": 6, "description": "Redfin region type; 6 is a city. Defaults to 6.", "maximum": 100, "minimum": 1, "type": "integer" } }, "required": [ "region_id" ], "title": "Redfin.listings.for_rent", "type": "object" }, "RedfinListingsSoldCompletedJob": { "additionalProperties": false, "properties": { "billing": { "$ref": "#/components/schemas/JobBilling" }, "capability": { "enum": [ "redfin.listings.sold" ], "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": [ "redfin" ], "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": { "end_page": 1, "has_more": false, "listings": [ { "address": "2327 N 140th St, Seattle, WA 98133", "area_sqft": 2570, "baths": 2, "beds": 3, "collected_at": "2026-10-15T06:03:37Z", "currency": "USD", "page": 1, "position": 1, "price": 800000, "property_id": "102610", "sold_date": "2026-10-13", "status": "Sold", "title": "2327 N 140th St", "url": "https://www.redfin.com/WA/Seattle/2327-N-140th-St-98133/home/102610", "year_built": 1947 } ], "next_page": 0, "pages_fetched": 1, "region_id": 16163, "region_type": 6, "sold_within_days": 90, "start_page": 1, "total_count": 1 } }, "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" }, "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": [ "redfin.agent.profile", "redfin.listings.for_rent", "redfin.listings.sold", "redfin.market.trends", "redfin.property.get", "redfin.search.listings" ], "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": [ "redfin" ], "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" }, "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" }, "RedfinPropertyGetExecuteRequest": { "additionalProperties": false, "description": "Fetch a public Redfin property page and return address, price, rooms, and media fields.", "example": { "capability": "redfin.property.get", "input": { "property_url": "https://www.redfin.com/WA/Seattle/130-29th-Ave-98122/home/148583" } }, "properties": { "capability": { "enum": [ "redfin.property.get" ], "type": "string" }, "input": { "$ref": "#/components/schemas/RedfinPropertyGetInput" }, "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": 45000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "type": "object" }, "RedfinPropertyGetInput": { "$schema": "https://json-schema.org/draft/2020-12/schema", "additionalProperties": false, "properties": { "property_url": { "maxLength": 2048, "pattern": "^https://([A-Za-z0-9-]+\\.)*redfin\\.com/", "type": "string" } }, "required": [ "property_url" ], "title": "Redfin.property.get", "type": "object" }, "RedfinListingsForRentExecuteRequest": { "additionalProperties": false, "description": "Search public Redfin rental listings with bounded pagination and rent or bedroom filters.", "example": { "capability": "redfin.listings.for_rent", "input": { "max_pages": 1, "max_rent": 3000, "min_beds": 2, "page": 1, "query": "Seattle WA rentals", "region_id": 16163, "region_type": 6 } }, "properties": { "capability": { "enum": [ "redfin.listings.for_rent" ], "type": "string" }, "input": { "$ref": "#/components/schemas/RedfinListingsForRentInput" }, "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": 45000, "minimum": 1, "type": "integer" } }, "required": [ "capability", "input" ], "type": "object" } }, "securitySchemes": { "BearerAuth": { "bearerFormat": "API Key", "scheme": "bearer", "type": "http" } } }, "info": { "description": "Get Redfin's housing market trends for a city as clean JSON: median sale price, homes sold, new listings, inventory and days on market, period by period with year-on-year change.\nThis spec includes only the live `Redfin Real Estate` capabilities exposed by Upscrape.\nExecution uses the generic `POST /execute` endpoint and job polling uses `GET /jobs/{id}`.\nSupported capabilities: `redfin.agent.profile`, `redfin.listings.for_rent`, `redfin.listings.sold`, `redfin.market.trends`, `redfin.property.get`, `redfin.search.listings`\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": "Redfin Real Estate 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": "redfin_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": "redfin.agent.profile", "input": { "profile_url": "https://www.redfin.com/real-estate-agents/chandra-gordon" } }, "schema": { "discriminator": { "mapping": { "redfin.agent.profile": "#/components/schemas/RedfinAgentProfileExecuteRequest", "redfin.listings.for_rent": "#/components/schemas/RedfinListingsForRentExecuteRequest", "redfin.listings.sold": "#/components/schemas/RedfinListingsSoldExecuteRequest", "redfin.market.trends": "#/components/schemas/RedfinMarketTrendsExecuteRequest", "redfin.property.get": "#/components/schemas/RedfinPropertyGetExecuteRequest", "redfin.search.listings": "#/components/schemas/RedfinSearchListingsExecuteRequest" }, "propertyName": "capability" }, "oneOf": [ { "$ref": "#/components/schemas/RedfinAgentProfileExecuteRequest" }, { "$ref": "#/components/schemas/RedfinListingsForRentExecuteRequest" }, { "$ref": "#/components/schemas/RedfinListingsSoldExecuteRequest" }, { "$ref": "#/components/schemas/RedfinMarketTrendsExecuteRequest" }, { "$ref": "#/components/schemas/RedfinPropertyGetExecuteRequest" }, { "$ref": "#/components/schemas/RedfinSearchListingsExecuteRequest" } ] } } }, "required": true }, "responses": { "200": { "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/RedfinAgentProfileCompletedJob" }, { "$ref": "#/components/schemas/RedfinListingsForRentCompletedJob" }, { "$ref": "#/components/schemas/RedfinListingsSoldCompletedJob" }, { "$ref": "#/components/schemas/RedfinMarketTrendsCompletedJob" }, { "$ref": "#/components/schemas/RedfinPropertyGetCompletedJob" }, { "$ref": "#/components/schemas/RedfinSearchListingsCompletedJob" }, { "$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": "redfin.agent.profile", "job_id": "00000000-0000-0000-0000-000000000001", "platform": "redfin", "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 Redfin Real Estate capability run", "tags": [ "Execution" ] } }, "/jobs/{id}": { "get": { "description": "Get job status and result", "operationId": "redfin_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/RedfinAgentProfileCompletedJob" }, { "$ref": "#/components/schemas/RedfinListingsForRentCompletedJob" }, { "$ref": "#/components/schemas/RedfinListingsSoldCompletedJob" }, { "$ref": "#/components/schemas/RedfinMarketTrendsCompletedJob" }, { "$ref": "#/components/schemas/RedfinPropertyGetCompletedJob" }, { "$ref": "#/components/schemas/RedfinSearchListingsCompletedJob" }, { "$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": "redfin.agent.profile", "job_id": "00000000-0000-0000-0000-000000000001", "platform": "redfin", "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 Redfin Real Estate job", "tags": [ "Jobs" ] } }, "/jobs/{id}/result": { "get": { "description": "Backward-compatible alias for `/jobs/{id}`.", "operationId": "redfin_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/RedfinAgentProfileCompletedJob" }, { "$ref": "#/components/schemas/RedfinListingsForRentCompletedJob" }, { "$ref": "#/components/schemas/RedfinListingsSoldCompletedJob" }, { "$ref": "#/components/schemas/RedfinMarketTrendsCompletedJob" }, { "$ref": "#/components/schemas/RedfinPropertyGetCompletedJob" }, { "$ref": "#/components/schemas/RedfinSearchListingsCompletedJob" }, { "$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": "redfin.agent.profile", "job_id": "00000000-0000-0000-0000-000000000001", "platform": "redfin", "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 Redfin Real Estate 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" } ] }