What each endpoint is for

Every endpoint in the API, grouped by the job it does, with why it's there and when to reach for it. For every parameter and field, see the reference.

Every call needs an API key. Reads (GET) work with any key; writes (POST and DELETE) need a key with the Read and write scope. The OpenAPI description itself is served without a key at GET /v1/openapi.json.

Start runs

• POST/v1/runsStart a run in one call. Send a list of properties and Beacon creates the report and queues its run. This is the call most integrations need. It costs one credit per property. You give it your own reference, such as a client or a market. That lets you find the run again, and lets the Lighthouse-compatible API read it. An optional timeZone sets the date the check-in dates start from. Without it, your company's time zone is used. Reference
• POST/v1/reportsSave a report without running it. Free. Use it when the list should be checked before anyone spends credits, or when one system builds lists and another decides when to run them. Reference
• POST/v1/reports/{id}/runsRun a saved report. Starts the run of a report made with POST /v1/reports. A report runs once, so this is a one-time step for each report. The body is optional: its one field, timeZone, works as on POST /v1/runs. Costs one credit per property. Reference

Follow runs

• GET/v1/runs/{id}Check one run. Its status and how many checks are left. Ask no more than once a minute, until complete is true. It keeps answering after the rows are deleted, so you keep the record of what ran and what it cost. Reference
• GET/v1/runsList and find runs. Newest first, filtered by your reference, status or start date. Because each run in the list carries its progress, one call can check on many runs at once. It's also how you find every past snapshot for one client or market. Reference
• GET/v1/reportsList reports. Every report this key can see, newest first, each with its properties and latest run. With a key set to All company runs, this includes reports your team builds in the app. Reference
• GET/v1/reports/{id}Get one report. Its name, currency, stay length, properties and run. Reference

Take the rates

• GET/v1/runs/{id}/resultsEvery room and rate. Every row the run captured: one per room and rate on each date, plus a row for each date with no rooms. Each row also carries the rate's flexibility, cancellation deadline and reschedulable flag. Take it in pages of JSON, or as one ndjson stream with format=ndjson, which takes a whole run in one request. You can read it while the run is still going. Its fields are in the field dictionary. Reference
• GET/v1/runs/{id}/ratesOne price per day. Picks one rate for each property and check-in date, using filters you set: guests, meal plan (room only, breakfast, half board, full board, all-inclusive, breakfast and lunch, lunch and dinner, dinner or lunch), only the public flexible rate, or a room type. Add perRoomType=1 for one rate per room type, so you compare doubles with doubles. Set los to the report's stay length; it defaults to 1. Use it when you want "the price" rather than every room. Available once the run has completed. See its fields. Reference

Look after runs

• POST/v1/runs/{id}/retryFetch failed checks again. Sometimes a date can't be fetched. Once a run completes, you can try any that failed with this call. It's free. You can use it once every 10 minutes per run. Retrying sooner answers 409 retry_cooldown. The run goes back to running and completes again when they're done. The full rules are in how a run progresses. Reference
• DELETE/v1/runs/{id}/resultsDelete Beacon's copy of the rows. Once you've stored a finished run's rows, tell Beacon to delete them. The run and its counters stay. Use it if your own policy says rates should be kept in one place only. Afterwards, results and rates answer 410 results_purged and failed checks can't be retried. The Lighthouse-compatible API skips a run whose rows are deleted. It reads the newest completed run with the same reference that still has rows and that the key can see, or answers general.missing if there isn't one. Your company may also have a retention period after which rows are deleted anyway. Reference
• GET/v1/creditsCheck your balance. How many credits your company has. Check it before a large run, or alert someone when it runs low. Credits are bought in the app. Reference

Lighthouse-compatible

These three endpoints answer like Lighthouse's v3 rates API, so code written for Lighthouse can read Beacon runs. They read runs started with a reference, which plays the part of a Lighthouse subscription. See Switching from Lighthouse.

• GET/lighthouse/v3/hotelsList subscriptions. One entry for each reference this key can read, with the first property as the subscription's main property and the rest as its competitors. A Lighthouse client uses this list to find what it can ask for. Reference
• GET/lighthouse/v3/ratesThe lowest rate per property and date. Lighthouse's filters, fields and CSV columns, read from the newest completed run for the subscription whose rows haven't been deleted. A few filters and fields work differently; see switching from Lighthouse. Reference
• GET/lighthouse/v3/roomtyperatesThe lowest rate per room type. As rates, but one rate for each property, date and room type. Reference