Journalist Lookup API
POST /api/v1/journalists/lookup takes one journalist from a name to a
deliverable email. Send a name, ideally with the outlet, an email address, or a
profile URL. Medialyst finds the person, returns the deliverable address it
holds, or runs live checks when it holds none.
The response never contains a masked or partial address. It returns a full
deliverable email or none at all.
Before You Start
Create an API key from the Medialyst Developers page,
store it in secret storage or an environment variable such as
MEDIALYST_API_KEY, and send it as a bearer token:
Authorization: Bearer <YOUR_API_KEY>No special API-key scope is needed. All examples use https://medialyst.ai/api
as the API base URL.
Look Up a Journalist
curl --request POST \
'https://medialyst.ai/api/v1/journalists/lookup' \
--header "Authorization: Bearer $MEDIALYST_API_KEY" \
--header 'Content-Type: application/json' \
--data '{ "q": "Kara Swisher at New York Magazine" }'Send exactly one of these fields:
| Field | Description |
|---|---|
q | A name, ideally with the outlet (Jane Doe at Example News), an email address, or a profile URL. Maximum 200 characters. |
journalist_id | A journalist_id from an earlier response, such as one of the candidates. |
With q you may also send "find_live": true. It skips the people Medialyst
holds and finds the named person at the named outlet live. Use it when an
ambiguous answer lists only the wrong people.
Every response has the same shape:
{
"status": "found",
"journalist": {
"journalist_id": "j_01HT...",
"name": "Kara Swisher",
"publication": "New York Magazine",
"domain": "nymag.com",
"url": "https://nymag.com/author/kara-swisher/",
"affiliation_status": "current"
},
"email": "[email protected]",
"candidates": [],
"credits_charged": 1,
"message": "Deliverable email found and 1 credit charged. Return this address to the user as given.",
"retry_after_seconds": null,
"free_plan": null
}message always says the next step in plain words.
affiliation_status says whether they still work at publication: current
(recent work there confirms it), former (they left), unconfirmed (we found
nothing recent either way), or null when nobody has checked yet.
Statuses
status | Meaning | What to do |
|---|---|---|
found | email is a deliverable address. | Use it as given, with the outlet and affiliation_status. |
checking | Medialyst is running live checks for this person. | Send the same body again after retry_after_seconds (about 20 seconds), until the status is found or not_found. |
not_found | Medialyst holds no deliverable email for this person. | Say so. Never guess an address. A new check is possible 24 hours after the last one. |
ambiguous | Several people match. candidates lists them. | Choose one by outlet, then send its journalist_id. If none is the person, send the same q with find_live: true. |
Repeating a call never starts a second live check and never charges twice. If
nobody in Medialyst matches a bare name, the response is not_found and asks
for the outlet. A name plus an outlet that matches nobody starts a live find,
so the response is checking.
Credits and Plans
A found email costs 1 credit (credits_charged: 1). A person your
organization already paid for in the last 30 days costs 0 credits. checking,
not_found, and ambiguous responses cost 0 credits.
| Plan | Lookups |
|---|---|
| Free | 3 lookups a day (UTC) through the API and MCP. The allowance is shared with POST /api/v1/journalists/enrich, where each source counts as one. Credits still apply. |
| Paid | No lookup allowance. Live checks count toward the plan's daily cap: Starter 50, Pro 150, Scale 500. |
On the free plan, free_plan shows what is left today:
{
"free_plan": {
"limit": 3,
"remaining": 2,
"reset_at": "2026-10-14T00:00:00.000Z"
}
}A lookup counts once it settles on one person or starts a live find. An
ambiguous response, or a bare name that matches nobody, does not count.
Asking about the same person again on the same day does not count again, so
calling back while checking is free. Upgrade at
medialyst.ai/pricing for more lookups.
Rate Limits
Lookup uses the API-wide limit of 60 requests per
minute. A rate-limited request
returns 429 RATE_LIMITED and a Retry-After header.
Common Errors
| HTTP status | Code | Meaning | What to do |
|---|---|---|---|
400 | INVALID_REQUEST | The body has neither or both of q and journalist_id, or q is longer than 200 characters. | Send exactly one field. |
401 | UNAUTHORIZED | The API key is missing or invalid. | Check the bearer token. |
402 | INSUFFICIENT_CREDITS | A deliverable address is held but the organization has no credits. | Add credits in Medialyst billing, then look up the same journalist again. |
404 | NOT_FOUND | The journalist_id is unknown. | Look up the person again with q and use only ids from that response. |
429 | FREE_PLAN_DAILY_LIMIT | The free plan used today's lookups. The body includes free_plan. | Upgrade, or try again after free_plan.reset_at. |
429 | LOOKUP_DAILY_CAP | The paid plan used today's live checks. | Try again tomorrow. Addresses already found stay available. |
429 | RATE_LIMITED | The API-wide request limit was reached. | Wait for Retry-After, then retry. |
Many People or Article URLs
For article authors, or for many journalists at once, use the async
journalist enrichment API
(POST /api/v1/journalists/enrich, up to 500 sources per job).
MCP
The hosted Medialyst MCP server exposes this route as
the lookup_journalist tool, with the same q and journalist_id inputs.
Authentication, credits, plan allowances, rate limits, and errors match direct
API calls. On FREE_PLAN_DAILY_LIMIT, INSUFFICIENT_CREDITS, or
LOOKUP_DAILY_CAP, an agent should relay the message and stop.