Foyer API

Limits

The limits are generous for a personal assistant and stop a runaway loop from hammering your account. They apply per Foyer member, across all of that member's keys and connected assistants together.

Rate limits

Limit	Value
Requests	60 a minute and 10,000 a day
Searches (`GET /v1/search`)	20 a minute, within the request limits

Over a limit, the API answers 429 with the code rate_limited, a Retry-After header in seconds, and details.retry_after_seconds. Wait that long, then retry. GET /v1/me shows your limits.

Python: retry after a 429

import time
import requests

def get(url, headers, params=None):
    while True:
        resp = requests.get(url, headers=headers, params=params, timeout=30)
        if resp.status_code != 429:
            resp.raise_for_status()
            return resp.json()
        time.sleep(int(resp.headers.get("Retry-After", "5")))

Sizes and lifetimes

What	Limit
Page size (`limit`)	1-100 items, 25 by default
Search results per request	1-50, 25 by default
Calls one search request examines	Up to 400, newest first. Pass `next_cursor` back to search further back
Search words (`q`)	2-200 characters, matched as one phrase, ignoring case
Note for your host	3-2,000 characters
Active keys per member	10
Key lifetime	Up to 90 days
Recording link	5 minutes

Being a good citizen

Ask for what changed since your last run with since, instead of reading every call each time.
Page with next_cursor; do not guess offsets.
A script that checks for new voicemails every five minutes uses about 300 requests a day, well within the daily limit.
Webhooks, when they arrive, will remove the need to poll. See Webhooks.