Developers

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:

FieldDescription
qA name, ideally with the outlet (Jane Doe at Example News), an email address, or a profile URL. Maximum 200 characters.
journalist_idA 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

statusMeaningWhat to do
foundemail is a deliverable address.Use it as given, with the outlet and affiliation_status.
checkingMedialyst 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_foundMedialyst holds no deliverable email for this person.Say so. Never guess an address. A new check is possible 24 hours after the last one.
ambiguousSeveral 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.

PlanLookups
Free3 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.
PaidNo 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 statusCodeMeaningWhat to do
400INVALID_REQUESTThe body has neither or both of q and journalist_id, or q is longer than 200 characters.Send exactly one field.
401UNAUTHORIZEDThe API key is missing or invalid.Check the bearer token.
402INSUFFICIENT_CREDITSA deliverable address is held but the organization has no credits.Add credits in Medialyst billing, then look up the same journalist again.
404NOT_FOUNDThe journalist_id is unknown.Look up the person again with q and use only ids from that response.
429FREE_PLAN_DAILY_LIMITThe free plan used today's lookups. The body includes free_plan.Upgrade, or try again after free_plan.reset_at.
429LOOKUP_DAILY_CAPThe paid plan used today's live checks.Try again tomorrow. Addresses already found stay available.
429RATE_LIMITEDThe 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.