How to Get Your Free Tavily API Key

Phonox already does a great job identifying vinyl records through Discogs and MusicBrainz. But some pressings — obscure promos, regional releases, limited runs — simply aren’t in those databases. That’s where Tavily comes in.

What is Tavily?

Tavily is an AI-optimised web-search API. Instead of returning a list of blue links, it returns structured, relevant content extracted from the web — exactly what an AI agent needs.

When Phonox can’t find a match through its primary music databases, it falls back to Tavily to search the wider internet. This means:

Obscure pressings that only appear on collector forums or Discogs forum threads can still be identified
Regional releases with non-standard catalogue numbers get matched more often
Test pressings and promos with limited documentation have a better chance of being recognised

Tavily is optional — Phonox works fine without it. But if you want the best possible identification rate, it’s worth the two minutes it takes to set up.

1. Create a free Tavily account

Go to app.tavily.com and click Sign up.

You can sign up with:

A Google account (fastest)
A GitHub account
An email address + password

No credit card required.

2. Get your API key

After signing in you land on the Tavily dashboard. Your API key is shown right on the overview page.

It looks like:

tvly-XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

Copy it — unlike some services, Tavily lets you view your key again from the dashboard at any time.

3. What’s included in the free tier?

Tavily’s free plan gives you 1,000 API calls per month at no cost. For Phonox this is more than enough — the Tavily fallback only triggers when primary databases don’t have a match, so typical usage is a handful of calls per session at most.

Plan	Monthly calls	Cost
Researcher (free)	1,000	$0
Scale	10,000+	From $100/mo

Most Phonox users will never come close to the free tier limit.

4. Give the key to Phonox

Option A — Interactive (recommended)

Run the Phonox CLI and choose option 3 — Configure API keys:

./start-cli.sh
# Select: 3) Configure API keys
# Paste your key at the TAVILY_API_KEY prompt

Option B — Direct command

./start-cli.sh configure --tavily "tvly-XXXX..."

Option C — Edit .env manually

Open (or create) the .env file in the Phonox root and add:

TAVILY_API_KEY=tvly-XXXX...

After setting the key, restart the containers:

./start-cli.sh restart

Troubleshooting

Phonox doesn’t seem to use Tavily at all Tavily is a fallback — it only activates when Discogs and MusicBrainz return no results. Try it with a record you know is obscure.

“Invalid API key” in the backend logs Make sure you copied the full key including the tvly- prefix. Re-run ./start-cli.sh configure --tavily "tvly-..." with the key in quotes to avoid whitespace issues.

“Rate limit exceeded” You’ve hit the 1,000 calls/month free tier limit. The counter resets on the 1st of each month. If you need more, Tavily offers paid plans at tavily.com/pricing.

That’s it — a free key, one command, and Phonox gains a powerful web-search fallback for those hard-to-find pressings.