Operations
Performance
What to expect from response times, what drives them, and how to get the most speed out of the integration.
How response time is measured
Three different numbers get called “API speed”, and they differ by an order of magnitude — so it is worth being precise about which one a figure refers to.
| Term | What it covers |
|---|---|
| Query time | Time spent inside the database for the request |
| Server time | Request in → response out. Query time plus stream-URL signing and serialisation |
| End-to-end | What your stopwatch sees — server time plus TLS and the public-internet round trip |
The API is served from a single region. If your servers are on another continent, budget 150–250 ms of network on top of every figure below. We quote p50/p95 rather than averages — an average hides the tail that your users actually feel.
Measured: search
Search is the most expensive endpoint in the API. Measured against the live catalog of 20,336 tracks, full pipeline, database query time:
The catalog is small enough that no endpoint is database-bound: the heaviest query in the product lands inside ~135 ms.
Browse-endpoint figures on request
We publish numbers we have measured, not estimates. Per-endpoint p95 figures for the browse routes come from a benchmark run against the host assigned to you, on a network path that matches your servers — ask your account manager and we will run it for your environment.
What drives the number
Stream URLs are signed per track. Every track in a response carries a freshly signed streamUrl, so a page of 100 does 100 signatures where a page of 20 does 20. Request the page size you will actually display — pageSize=20 is the default for this reason.
Search degrades rather than stalls. The semantic channel calls an embedding service with a hard 400 ms cap. On timeout that channel is dropped and results are fused from the lexical and fuzzy channels alone — measurably faster, still useful, never a 500. Your worst case is bounded, not open-ended.
Test mode is slower than live. A test_ token is forwarded internally to the test environment and the response relayed back, which roughly doubles server time. Benchmark with live credentials; test-mode timings are not representative.
Token minting is deliberately slow. Secret verification uses bcrypt, which is designed to cost around 100 ms. That is why the endpoint allows 30/min and why you should cache the token for its full hour.
Getting the best speed
1. Cache the access token. Valid one hour. Refresh ~5 minutes before expiry rather than minting per call.
2. Cache the filter master list. It changes rarely — fetch it at startup, not per screen.
3. Ask for the page you will show. Page size is capped at 100, but smaller pages are faster.
4. Cache metadata, never the stream URL. Signed URLs expire in 30 minutes; keep any cache TTL below that.
5. Reuse HTTP connections. Keep-alive removes a TLS handshake per call — on a cross-region path that can cost more than the request itself.
6. Debounce search. Fire on a pause in typing, not per keystroke.
7. Back off on 429. Use the RateLimit-Reset header instead of retrying immediately.
Throughput
Catalog endpoints allow 6000 requests/minute per client — 100 requests per second sustained. See Rate limits for the full budget.