Celebrity API

Frequently Asked Questions

• Can I use the Celebrity API for commercial purposes?

  Yes, but you must have a premium subscription. Commercial use of the Celebrity API is not permitted on the free tier. See our pricing page to choose a plan that fits your needs.

• How do I get an API key and start using the Celebrity API?

  Sign up for a free account to instantly get your API key, then pass it in the X-Api-Key header on every request. The documentation above includes ready-to-run examples in cURL, Python, JavaScript, Node.js, and more.

• What happens if I exceed my quota for the month?

  Your API requests will simply be denied once you hit your monthly quota — you will never be charged more than the plan you signed up for. To increase your quota, you can upgrade your plan any time on our pricing page.

• What happens if a request to the Celebrity API fails?

  The API responds with a standard HTTP status code and a JSON error message describing the problem. See our error codes reference for the full list of codes and how to resolve each one, or contact support if you need help.

• How do I filter celebrities by wealth, height, or nationality instead of searching by name?

  The /v1/celebrity endpoint accepts several optional filter parameters, including min_net_worth and max_net_worth (in US dollars), min_height and max_height (in meters, e.g. 1.65), and nationality as an ISO 3166 Alpha-2 country code such as US. You can combine these without a name value to discover celebrities matching a profile; see the full parameter list in the API catalog.

• How many results does a single Celebrity API request return, and how do I get more?

  Each request returns a JSON array of up to 30 celebrities matching your search parameters. To page beyond the first 30 results, use the offset parameter, which is a premium feature available on paid plans.

• What fields are included in a celebrity record?

  Each object includes the celebrity's name, net_worth (in US dollars), gender (male or female), nationality (a 2-letter country code), an occupation array, height in meters, and birthday in YYYY-MM-DD format. If a request fails you will instead receive an error response, documented on the error codes page.

• Does this API cover historical or deceased figures, or just famous contemporary people?

  The Celebrity API focuses on famous living and contemporary individuals such as actors, athletes, politicians, and business leaders. For notable people from history, use the dedicated Historical Figures API instead.