airbnb-full

Complete Airbnb stay data toolkit via StayingAPI.com. Use when the user explicitly asks about an Airbnb listing, its price, reviews or availability, listings to book in a place, or bulk/automated stay-data jobs.

When to use this skill

Each tool call consumes Staying API credits, so this skill activates only when the user's request is genuinely about Airbnb stay data — not when a listing link or place name merely appears in passing.

DO use when the user:

• Pastes an Airbnb URL and asks about that listing → lookup_stay_by_url
• Gives a listing id or address and asks about the place, its reviews, or availability → lookup_stay_by_id / lookup_stay_by_address
• Asks for a specific facet (photos, reviews, host, amenities, availability, pricing, location, rating) → get_stay_*
• Asks to find stays matching criteria (location, dates, price, beds, capacity) → search_stays (or search_superhost / search_instant_book / search_luxury)
• Wants to resolve many listings at once → batch_stays
• Wants to be notified when an async job finishes → create_webhook
• Asks about their credit balance or usage → get_account / get_usage

Do NOT use when:

• An Airbnb link or address appears incidentally (email signatures, news articles, unrelated content)
• The user is discussing travel abstractly without asking for data on a specific listing or search
• The user has not signaled they want a lookup

When intent is ambiguous, ask the user to confirm before calling a tool. These tools cost credits and return large records.

Tools

All tools return a Python dict — the API response on success, or {"error": ..., "detail": ...} on failure. The get_stay_* sub-resource tools accept stay_id (cheapest), url, or address.

Lookup

• lookup_stay_by_id(stay_id, fields=None) — 1 credit. Full canonical Stay record.
• lookup_stay_by_url(url, fields=None) — 1 credit. Same, from an airbnb.com/rooms/<id> URL.
• lookup_stay_by_address(address, fields=None) — 3 credits. Resolve from a street address.

Sub-resources (1 credit each)

• get_stay_photos(...) — photo gallery
• get_stay_reviews(...) — reviews + rating breakdown
• get_stay_host(...) — host profile
• get_stay_amenities(...) — amenities by category
• get_stay_availability(...) — 12-month availability calendar
• get_stay_pricing(...) — nightly rate, fees, currency
• get_stay_location(...) — coordinates and address
• get_stay_rating(...) — star rating and review-count summary

Search

• search_stays(location=None, search_urls=None, check_in=None, check_out=None, price_min=None, price_max=None, min_beds=None, min_bedrooms=None, min_bathrooms=None, adults=None, children=None, infants=None, pets=None, currency=None, locale=None, max_items=50, fields=None) — 1 credit per result, max_items up to 240.
• search_superhost(...) / search_instant_book(...) / search_luxury(...) — same filters, preset segments.
• search_stays_with_details(...) — async; returns a job envelope (poll with get_job / get_job_results).

Batch + jobs

• batch_stays(targets, webhook_id=None) — async. targets is a list of ids, URLs, and/or addresses (up to 500). Returns a job envelope.
• list_jobs(status=None, type=None, since=None, limit=50, offset=0) — list async jobs.
• get_job(job_id) — job status.
• get_job_results(job_id, limit=50, offset=0, format="json") — paginated results (json | csv | ndjson).

Webhooks

• create_webhook(url, events, description=None) — events from: job.queued, job.running, job.succeeded, job.failed, stay.cached. Deliveries are HMAC-signed.
• list_webhooks() · get_webhook(webhook_id) · delete_webhook(webhook_id) · get_webhook_deliveries(webhook_id)

Account

• get_account() — account, plan, and credit balance (GET /v1/me).
• get_usage(since=None, limit=50) — recent metered calls.

Equivalent MCP tools

The hosted MCP server (https://api.stayingapi.com/mcp, streamable-HTTP, Bearer sk_... or OAuth 2.1 PKCE scope mcp:access) exposes five tools — an alternative to this skill: lookup_stay_by_id, lookup_stay_by_url, search_stays, get_stay_photos, get_stay_reviews.

Authentication

Set STAYINGAPI_KEY to your Staying API key. Keys are sk_... strings.

export STAYINGAPI_KEY="sk_..."

Get a free key with 100 credits at https://stayingapi.com/app/keys — no card required.

Pricing

| Plan | Price | Credits | Rate limit | |---|---|---|---| | Free | $0 | 100 (one-time) | 20/min | | Monthly | $5/mo | 400/month | 200/min | | Annual | $54/yr | 5,000/year | 300/min | | Enterprise | Custom | Custom | 1,500/min |

One credit per stay record returned. Search bills 1 credit per result; by-address and address batch entries weigh 3. Failed calls (4xx/5xx) do not consume credits. Credits roll forward and don't expire.

Errors

All functions return a Python dict. On success it contains the API response. On failure it contains an error key:

• {"error": "auth", ...} — STAYINGAPI_KEY is missing or invalid
• {"error": "HTTP 404", ...} — listing or job not found
• {"error": "HTTP 429", ...} — rate-limited; back off and retry
• {"error": "network", ...} — DNS/connection failure

API reference

• OpenAPI spec: https://stayingapi.com/openapi.json
• Hosted MCP server (alternative to this skill): https://api.stayingapi.com/mcp
• MCP server card: https://stayingapi.com/.well-known/mcp/server-card.json
• Quickstart: https://stayingapi.com/quickstart/

Trademark

Staying API is an independent service and is not affiliated with, endorsed by, or sponsored by Airbnb, Inc. "Airbnb" is a registered trademark of Airbnb, Inc.