# NinjaPear Overview NinjaPear is a B2B Company Intelligence platform focused on data ownership and ethical sourcing. As a first-party provider, we maintain a sustainable ecosystem of proprietary and legally vetted data. Our mission is to provide a reliable data infrastructure, enabling businesses to develop and scale value-added applications and workflows with confidence. ## For AI Agents Building with an AI coding agent? Use the plain Markdown version of these docs — optimized for LLMs and AI tools like Claude, Cursor, and ChatGPT: - **[LLM-friendly docs (Markdown)](https://nubela.co/llms-full.txt)** — full API reference as plain text, ready to paste or drag-and-drop into any AI chat - **[llms.txt](https://nubela.co/llms.txt)** — lightweight index for AI agent discovery - **[OpenAPI 3.0 Spec](https://nubela.co/api/openapi3.yaml)** — machine-readable API schema ## Explain it to me like I'm 5 - Get a list of customers, investors, and partners of any company with the [Customer Listing Endpoint](#customer-listing-endpoint). - Find competitors of any company and why they compete with the [Competitor Listing Endpoint](#competitor-listing-endpoint). - Get the logo of any company for free with the [Company Logo Endpoint](#company-logo-endpoint). - Get full company details like industry, description, executives, and office locations with the [Company Details Endpoint](#company-details-endpoint). - Get the employee count of any company with the [Employee Count Endpoint](#employee-count-endpoint). - Get recent blog posts and social media updates of any company with the [Company Updates Endpoint](#company-updates-endpoint). - Get the full funding history and investors of any company with the [Company Funding Endpoint](#company-funding-endpoint). - Look up a person's profile, job history, and education from their work email with the [Person Profile Endpoint](#person-profile-endpoint). - Find people similar to a target person — same role at competing companies — with the [Similar People Endpoint](#similar-people-endpoint). - Check if an email address is disposable or from a free email provider with the [Disposable Email Checker Endpoint](#disposable-email-checker-endpoint). - Monitor companies for new blog posts, tweets, and website changes via RSS with the [Monitor API](#monitor-api). - Check your remaining API credits with the [View Credit Balance Endpoint](#view-credit-balance-endpoint). ## Authentication ```shell curl "https://nubela.co/api/v1/customer/listing" \ -H "Authorization: Bearer YOUR_API_KEY" ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.CustomerAPIApi(api_client) response = api.get_customer_listing(website="https://example.com") ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; var bearerAuth = defaultClient.authentications["bearerAuth"]; bearerAuth.accessToken = "YOUR_API_KEY"; var api = new NinjaPear.CustomerAPIApi(); api.getCustomerListing("https://example.com").then(function (data) { console.log(data); }); ``` NinjaPear's API uses bearer tokens to authenticate users. Each user is assigned a randomly generated secret key under the [API section in the dashboard](https://nubela.co/dashboard). The bearer token is injected in the `Authorization` header. ## Client Libraries We provide official client libraries for JavaScript and Python to make integrating with the NinjaPear API easier. ### JavaScript (Node.js) ```shell npm install ninjapear ``` ```python # JavaScript library - see JavaScript tab ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; var bearerAuth = defaultClient.authentications["bearerAuth"]; bearerAuth.accessToken = "YOUR_API_KEY"; // Now you can use any API class var companyApi = new NinjaPear.CompanyAPIApi(); var customerApi = new NinjaPear.CustomerAPIApi(); var contactApi = new NinjaPear.ContactAPIApi(); var metaApi = new NinjaPear.MetaAPIApi(); ``` - [npm package](https://www.npmjs.com/package/ninjapear) - [GitHub repository](https://github.com/NinjaPear/ninjapear-js) ### Python ```shell uv add ninjapear # or: pip install ninjapear ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) # Use the client with a context manager with ninjapear.ApiClient(configuration) as api_client: company_api = ninjapear.CompanyAPIApi(api_client) customer_api = ninjapear.CustomerAPIApi(api_client) contact_api = ninjapear.ContactAPIApi(api_client) meta_api = ninjapear.MetaAPIApi(api_client) ``` ```javascript // Python library - see Python tab ``` - [PyPI package](https://pypi.org/project/ninjapear/) - [GitHub repository](https://github.com/NinjaPear/ninjapear-py) ## Rate limit You can make up to 300 requests to our API every minute. The window for the rate limit is 5 minutes. This means you can burst up to 1500 requests every 5 minutes. At periods of high load, our system might tighten rate limits for all accounts to ensure that our services remain accessible for all users. We return a status code of error 429 when you are rate limited. You can also get a status code error of 429 if the capacity on our end limits us. You should handle 429 errors and apply exponential backoff. Accounts on trial (that is before any top ups have been made) are limited to 2 requests every minute. You get the normal rate limit upon making at least one credit top-up. ### Rate limit for Free APIs To sustainably provide free APIs, rate limit for free APIs depends on your subscription plan: - PAYG plan: 2 requests/min - $49/mo plan: 20 requests/min - $299/mo plan: 50 requests/min - $899/mo plan: 100 requests/min - $1899/mo plan: 300 requests/min ## Credits Each valid request requires at least `0.1` credit to be processed, unless it is a free API endpoint. A credit is consumed if and only if the request is parsed successfully. A successful request is a request that returns with a `200` HTTP status code. ## Timeouts and API response time NinjaPear API endpoints take `30-60` seconds to complete. You are encouraged to make concurrent requests to our API service to maximize throughput. See [this post](https://nubela.co/blog/how-to-maximize-throughput-on-proxycurl/) on how you can maximise throughput. We recommend a timeout of `100` seconds. ## Errors These are the common errors that could be returned by our API: | HTTP Code | Charge? | Description | | --------- | ------- | ------------------------------------------------------------------------------------------ | | 400 | No | Invalid parameters provided. Refer to the documentation and message body for more info | | 401 | No | Invalid API Key | | 403 | No | You have run out of credits | | 404 | Yes | The requested resource (e.g., user profile, company) could not be found | | 410 | No | This API is deprecated | | 429 | No | Rate limited. Please retry | | 500 | No | There is an error with our API. Please [Contact us](mailto:hello@nubela.co) for assistance | | 503 | No | Enrichment failed, please retry. | You will never be charged for **failed requests**. ## Backward Compatibility Guarantee We are committed to ensuring that our API remains backward compatible, allowing you to integrate with confidence. Our backward compatibility guarantee means that we will not introduce changes that break existing functionality or remove endpoints without a deprecation period. To be specific, we will not introduce breaking changes in the following ways: 1. We will not remove documented parameters and response attributes. 2. We will not change the data type as documented in our API responses. However, the following are not considered breaking changes: - Adding attributes/parameters to API endpoints without prior notice. - Adding additional response or requests headers to our API endpoints without prior notice. We highly recommend integrating our API in a way that would not break should new response attributes or headers be introduced. If we make changes to our API, we will provide clear documentation and sufficient notice (30 days) to ensure a seamless transition. Notices will be shared via newsletter emails, Twitter/X posts and updates to our blog. # Customer API ## Customer Listing Endpoint `GET /api/v1/customer/listing` Cost: `1` credit / request + `2` credit / company returned. Credits are charged even when the request returns an empty result. Get a list of highly-probable customers, investors, and partners/platforms of a target company, categorized by relationship type. ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "website=https://www.stripe.com" \ "https://nubela.co/api/v1/customer/listing" ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.CustomerAPIApi(api_client) response = api.get_customer_listing(website="https://www.stripe.com") print(response) ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; defaultClient.authentications["bearerAuth"].accessToken = "YOUR_API_KEY"; var api = new NinjaPear.CustomerAPIApi(); api.getCustomerListing("https://www.stripe.com").then(function (data) { console.log(data); }); ``` > Example response: ```json { "customers": [ { "name": "Apple", "description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide.", "tagline": "Think different.", "website": "https://www.apple.com", "company_logo_url": "https://nubela.co/api/v1/company/logo?website=https%3A%2F%2Fwww.apple.com", "id": "abc123", "industry": 45202030, "specialties": ["Technology", "Consumer Electronics"], "x_profile": "https://x.com/Apple" } ], "investors": [ { "name": "Sequoia Capital", "description": "Sequoia Capital is a venture capital firm focused on technology companies.", "tagline": null, "website": "https://www.sequoiacap.com", "company_logo_url": "https://nubela.co/api/v1/company/logo?website=https%3A%2F%2Fwww.sequoiacap.com", "id": "def456", "industry": 40203010, "specialties": ["Venture Capital", "Growth Equity"], "x_profile": "https://x.com/sequoia" } ], "partner_platforms": [ { "name": "Amazon Web Services", "description": "Amazon Web Services provides cloud computing platforms and APIs.", "tagline": null, "website": "https://aws.amazon.com", "company_logo_url": "https://nubela.co/api/v1/company/logo?website=https%3A%2F%2Faws.amazon.com", "id": "ghi789", "industry": 45101010, "specialties": ["Cloud Computing", "Infrastructure"], "x_profile": "https://x.com/awscloud" } ], "next_page": "https://nubela.co/api/v1/customer/listing?website=https://www.stripe.com&cursor=abc123" } ``` ### URL Parameters | Parameter | Required | Description | Example | | ---------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `website` | Yes | The website URL of the target company | `https://www.stripe.com` | | `cursor` | No | Pagination cursor from `next_page` in a previous response | `abc123` | | `page_size` | No | Number of results per page (1-200, default 200) | `50` | | `quality_filter` | No | Filter out low-quality results (junk TLDs like `.top`, `.xyz` and unreachable websites). Set to `false` to include all results. (default: `true`) | `false` | ### Response | Key | Description | Example | | ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | | `customers` | A list of companies that are probable customers of the target company. Entities that pay for the target's product/service. | List of CustomerCompany objects | | `investors` | A list of companies that are investors (VC firms, PE funds, angel networks) of the target company. | List of CustomerCompany objects | | `partner_platforms` | A list of companies that are partners, platforms, or service providers the target company uses or integrates with (tech stack, media, agencies). | List of CustomerCompany objects | | `next_page` | The API URI that serves as the cursor for pagination. Following this URL with your API key will lead to the next page of results. This will be null for the final page. | `https://nubela.co/api/v1/customer/list?...` | ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | ------------------------------------------------------------- | | 400 | No | Unable to extract enough information about the target company | ### CustomerCompany | Key | Description | Example | | ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | | `name` | Company name | `"Apple"` | | `description` | A brief description of the company | `"Apple Inc. designs, manufactures, and markets smartphones..."` | | `tagline` | Company tagline or slogan | `"Think different."` | | `website` | Company website URL | `"https://www.apple.com"` | | `company_logo_url` | URL to the Company Logo API for this company. Powered by [Company Logo Endpoint](#company-logo-endpoint). Authenticate with your bearer token. `null` if no website. | `"https://nubela.co/api/v1/company/logo?website=https%3A%2F%2Fwww.apple.com"` | | `id` | Unique identifier | `"abc123"` | | `industry` | GICS 8-digit industry code | `45202030` | | `specialties` | List of company specialties | `["Technology"]` | | `x_profile` | X (Twitter) profile URL | `"https://x.com/Apple"` | > **Note on `company_logo_url`:** This URL is powered by the [Company Logo Endpoint](#company-logo-endpoint). Authenticate with your Bearer token (same as the main API). These are temporal links — the recommended approach is to download the image via the URL as soon as the response is returned and host the image on your end. ### Response Headers | Header Key | Description | Example | | ------------------------- | --------------------------------------- | ------- | | `X-NinjaPear-Credit-Cost` | Total cost of credits for this API call | `10` | # Competitor API ## Competitor Listing Endpoint `GET /api/v1/competitor/listing` Cost: `2` credits / competitor returned. Minimum `5` credits per request, charged even when no results are found. Get a list of competitor companies for a target company, with the reason for competition. ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "website=https://www.stripe.com" \ "https://nubela.co/api/v1/competitor/listing" ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.CompetitorAPIApi(api_client) response = api.get_competitor_listing(website="https://www.stripe.com") print(response) ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; defaultClient.authentications["bearerAuth"].accessToken = "YOUR_API_KEY"; var api = new NinjaPear.CompetitorAPIApi(); api.getCompetitorListing("https://www.stripe.com").then(function (data) { console.log(data); }); ``` > Example response: ```json { "competitors": [ { "company_details_url": "https://nubela.co/api/v1/company/details?website=https://www.adyen.com", "website": "https://www.adyen.com", "competition_reason": "product_overlap" }, { "company_details_url": "https://nubela.co/api/v1/company/details?website=https://squareup.com", "website": "https://squareup.com", "competition_reason": "product_overlap" }, { "company_details_url": "https://nubela.co/api/v1/company/details?website=https://www.checkout.com", "website": "https://www.checkout.com", "competition_reason": "organic_keyword_overlap" } ] } ``` ### URL Parameters | Parameter | Required | Description | Example | | --------- | -------- | ------------------------------------- | ------------------------ | | `website` | Yes | The website URL of the target company | `https://www.stripe.com` | ### Response | Key | Description | Example | | ------------- | ------------------------------------------------------ | ------------------------------------------------------- | | `competitors` | A list of competitor companies for the target company. | List of [CompetitorCompany](#competitorcompany) objects | ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | ------------------------------------------------------------- | | 400 | No | Unable to extract enough information about the target company | ### CompetitorCompany | Key | Description | Example | | --------------------- | ------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------- | | `company_details_url` | URL to the Company Details endpoint for this competitor. Authenticate with your bearer token to retrieve full company details. | `"https://nubela.co/api/v1/company/details?website=https://www.adyen.com"` | | `website` | Company website URL | `"https://www.adyen.com"` | | `competition_reason` | Why this company is considered a competitor. One of the values from the [Competition Reason](#competition-reason-enum) enum. | `"product_overlap"` | ### Competition Reason Enum | Value | Description | | ------------------------- | ------------------------------------------------------- | | `organic_keyword_overlap` | Both companies rank for similar organic search keywords | | `product_overlap` | Both companies offer similar products or services | ### Response Headers | Header Key | Description | Example | | ------------------------- | --------------------------------------- | ------- | | `X-NinjaPear-Credit-Cost` | Total cost of credits for this API call | `4` | # Company API ## Company Logo Endpoint `GET /api/v1/company/logo` Cost: `0` credit / successful request. (FREE) Retrieve the logo of a company given its website URL. Returns the logo as a PNG image (128x128). ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "website=https://www.stripe.com" \ "https://nubela.co/api/v1/company/logo" \ --output logo.png ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.CompanyAPIApi(api_client) logo_data = api.get_company_logo(website="https://www.stripe.com") # Save the logo image with open("logo.png", "wb") as f: f.write(logo_data) ``` ```javascript var NinjaPear = require("ninjapear"); var fs = require("fs"); var defaultClient = NinjaPear.ApiClient.instance; defaultClient.authentications["bearerAuth"].accessToken = "YOUR_API_KEY"; var api = new NinjaPear.CompanyAPIApi(); api.getCompanyLogo("https://www.stripe.com").then(function (data) { // Save the logo image fs.writeFileSync("logo.png", Buffer.from(data)); }); ``` > Example response: > ![Company Logo Example](/assets/docs/company-logo-example.png) A raw PNG image binary (Content-Type: `image/png`). ### URL Parameters | Parameter | Required | Description | Example | | --------- | -------- | ------------------------------------- | ------------------------ | | `website` | Yes | The website URL of the target company | `https://www.stripe.com` | ### Response A `200` response returns the logo as a raw PNG image with `Content-Type: image/png`. ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | ---------------------------------- | | 404 | No | No logo found for the given domain | ### Response Headers | Header Key | Description | Example | | ------------------------- | --------------------------------------- | ------- | | `X-NinjaPear-Credit-Cost` | Total cost of credits for this API call | `0` | ## Company Details Endpoint `GET /api/v1/company/details` Cost: `2` credits / request (base). Add `2` credits when `include_employee_count=true`. Add `1` credit when `follower_count=include`. Maximum total: `5` credits. Credits are charged even if no data found. Retrieve the details of a company given its website URL. Returns company metadata including description, industry, social media URLs, and more. ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "website=https://www.stripe.com" \ "https://nubela.co/api/v1/company/details" ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.CompanyAPIApi(api_client) details = api.get_company_details(website="https://www.stripe.com") print(details) ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; defaultClient.authentications["bearerAuth"].accessToken = "YOUR_API_KEY"; var api = new NinjaPear.CompanyAPIApi(); api.getCompanyDetails("https://www.stripe.com").then(function (data) { console.log(data); }); ``` > Example response (private company): ```json { "websites": ["https://stripe.com", "https://stripe.dev"], "description": "Stripe is a technology company that builds economic infrastructure for the internet.", "industry": 45102010, "company_type": "PRIVATELY_HELD", "founded_year": 2010, "specialties": ["Payments", "Financial Services", "APIs"], "name": "Stripe", "tagline": "Financial infrastructure for the internet", "logo_url": "https://nubela.co/api/v1/company/logo?website=https://stripe.com", "cover_pic_url": "https://example.com/stripe-cover.png", "facebook_url": "https://facebook.com/stripe", "twitter_url": "https://twitter.com/stripe", "instagram_url": null, "employee_count": 8000, "addresses": [ { "address_type": "HEADQUARTERS", "line1": "354 Oyster Point Blvd", "line2": null, "city": "South San Francisco", "state": "CA", "postal_code": "94080", "country_code": "US", "country": "United States", "is_primary": true } ], "executives": [ { "name": "Patrick Collison", "title": "Chief Executive Officer", "role": "CEO" } ], "similar_companies": "https://nubela.co/api/v1/competitor/listing?website=https%3A%2F%2Fstripe.com", "updates": "https://nubela.co/api/v1/company/updates?website=https%3A%2F%2Fstripe.com", "funding": "https://nubela.co/api/v1/company/funding?website=https%3A%2F%2Fstripe.com", "public_listing": null, "follower_count": 272190, "following_count": 555 } ``` > Example response (public company): ```json { "websites": ["https://apple.com"], "description": "Apple Inc. designs, manufactures, and markets smartphones, personal computers, tablets, wearables, and accessories worldwide.", "industry": 45202030, "company_type": "PUBLIC_COMPANY", "founded_year": 1976, "specialties": ["Consumer Electronics", "Software", "Services"], "name": "Apple", "tagline": "Think different", "logo_url": "https://nubela.co/api/v1/company/logo?website=https://apple.com", "cover_pic_url": "https://example.com/apple-cover.png", "facebook_url": "https://facebook.com/apple", "twitter_url": "https://twitter.com/apple", "instagram_url": "https://instagram.com/apple", "employee_count": 164000, "addresses": [ { "address_type": "HEADQUARTERS", "line1": "One Apple Park Way", "line2": null, "city": "Cupertino", "state": "CA", "postal_code": "95014", "country_code": "US", "country": "United States", "is_primary": true } ], "executives": [ { "name": "Tim Cook", "title": "Chief Executive Officer", "role": "CEO" } ], "similar_companies": "https://nubela.co/api/v1/competitor/listing?website=https%3A%2F%2Fapple.com", "updates": "https://nubela.co/api/v1/company/updates?website=https%3A%2F%2Fapple.com", "funding": "https://nubela.co/api/v1/company/funding?website=https%3A%2F%2Fapple.com", "follower_count": 9500000, "following_count": 1, "public_listing": { "stock_symbol": "AAPL", "ipo_date": "1980-12-12", "isin": "US0378331005", "figi": "BBG000B9XRY4", "cusip": "037833100", "lei": "HWUPKR0MPOU8FGXBT394", "cik": "0000320193", "sic_code": "3571", "revenue_usd": 383285000000, "revenue_captured_at": "2024-09-28", "ebitda_usd": 134000000000, "ebitda_captured_at": "2024-09-28" } } ``` ### URL Parameters | Parameter | Required | Description | Example | | ------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ | | `website` | Yes | The website URL of the target company | `https://www.stripe.com` | | `include_employee_count` | No | Fetch fresh employee count data via web search. Adds `2` credits to the request cost. Valid values: `true`, `false` (default). | `true` | | `follower_count` | No | Include Twitter/X follower and following counts. Adds `1` credit to the request cost. Valid values: `include`. Omit or pass any other value to exclude. | `include` | ### Response | Key | Description | Example | | -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------- | | `websites` | List of all company website URLs | `["https://stripe.com", "https://stripe.dev"]` | | `description` | A brief description of the company | `"Stripe is a technology company..."` | | `industry` | GICS 8-digit industry code | `45102010` | | `company_type` | Type of company (PUBLIC_COMPANY, PRIVATELY_HELD, GOVERNMENT_AGENCY, NON_PROFIT, EDUCATIONAL, PARTNERSHIP, SELF_EMPLOYED, SELF_OWNED) | `"PRIVATELY_HELD"` | | `founded_year` | Year the company was founded | `2010` | | `specialties` | List of company specialties | `["Payments", "Financial Services"]` | | `name` | Company name | `"Stripe"` | | `tagline` | Company tagline or slogan | `"Financial infrastructure for the internet"` | | `logo_url` | URL to the [Company Logo endpoint](#company-logo-endpoint). Authenticate with your API key bearer token. | `"https://nubela.co/api/v1/company/logo?website=https://stripe.com"` | | `cover_pic_url` | URL to the company's cover/banner image | `"https://example.com/cover.png"` | | `facebook_url` | Facebook profile URL | `"https://facebook.com/stripe"` | | `twitter_url` | Twitter/X profile URL | `"https://twitter.com/stripe"` | | `instagram_url` | Instagram profile URL | `null` | | `employee_count` | Estimated number of employees | `8000` | | `employee_count_range_min` | Lower bound of employee count range. Only present when `include_employee_count=true`. | `7500` | | `employee_count_range_max` | Upper bound of employee count range. Only present when `include_employee_count=true`. | `8500` | | `follower_count` | Number of Twitter/X followers. Only present when `follower_count=include`. | `272190` | | `following_count` | Number of Twitter/X accounts followed. Only present when `follower_count=include`. | `555` | | `addresses` | List of company addresses | \[[Address Object](#address-object)\] | | `executives` | List of company executives and board members | \[[Executive Object](#executive-object)\] | | `similar_companies` | URL to the [Competitor Listing endpoint](#competitor-listing-endpoint). Authenticate with your bearer token to retrieve competitors. | `"https://nubela.co/api/v1/competitor/listing?website=https%3A%2F%2Fstripe.com"` | | `updates` | URL to the [Company Updates endpoint](#company-updates-endpoint). Authenticate with your bearer token to retrieve updates. | `"https://nubela.co/api/v1/company/updates?website=https%3A%2F%2Fstripe.com"` | | `funding` | URL to the [Company Funding endpoint](#company-funding-endpoint). Authenticate with your bearer token to retrieve funding history. | `"https://nubela.co/api/v1/company/funding?website=https%3A%2F%2Fstripe.com"` | | `public_listing` | Public company data including stock info and financials. `null` for private companies. | [PublicListing Object](#publiclisting-object) | ### Address Object | Key | Description | Example | | -------------- | ------------------------------------------------------------------ | ------------------------- | | `address_type` | Type of address (HEADQUARTERS, REGISTERED, BRANCH, MAILING, OTHER) | `"HEADQUARTERS"` | | `line1` | Street address line 1 | `"354 Oyster Point Blvd"` | | `line2` | Street address line 2 | `null` | | `city` | City name | `"South San Francisco"` | | `state` | State, province, or region | `"CA"` | | `postal_code` | Postal/ZIP code | `"94080"` | | `country_code` | ISO 3166-1 alpha-2 country code | `"US"` | | `country` | Full country name | `"United States"` | | `is_primary` | Whether this is the primary address | `true` | ### Executive Object | Key | Description | Example | | ------- | --------------------------------------------------------------------------------------------------------------------------- | --------------------------- | | `name` | Full name of the executive | `"Patrick Collison"` | | `title` | Job title | `"Chief Executive Officer"` | | `role` | Normalized role type (CEO, CFO, COO, CTO, CMO, PRESIDENT, VICE_PRESIDENT, DIRECTOR, BOARD_MEMBER, CHAIRMAN, FOUNDER, OTHER) | `"CEO"` | ### PublicListing Object This object is only present (non-null) for public companies. For private companies, `public_listing` will be `null`. | Key | Description | Example | | --------------------- | ------------------------------------------------ | ------------------------ | | `stock_symbol` | Stock ticker symbol | `"AAPL"` | | `ipo_date` | IPO date in ISO format | `"1980-12-12"` | | `isin` | International Securities Identification Number | `"US0378331005"` | | `figi` | Financial Instrument Global Identifier | `"BBG000B9XRY4"` | | `cusip` | CUSIP identifier | `"037833100"` | | `lei` | Legal Entity Identifier | `"HWUPKR0MPOU8FGXBT394"` | | `cik` | SEC Central Index Key | `"0000320193"` | | `sic_code` | SEC Standard Industrial Classification code | `"3571"` | | `revenue_usd` | Annual revenue in USD | `383285000000` | | `revenue_captured_at` | Date when revenue data was captured (ISO format) | `"2024-09-28"` | | `ebitda_usd` | EBITDA in USD | `134000000000` | | `ebitda_captured_at` | Date when EBITDA data was captured (ISO format) | `"2024-09-28"` | ### Response Headers | Header Key | Description | Example | | ------------------------- | --------------------------------------- | ------- | | `X-NinjaPear-Credit-Cost` | Total cost of credits for this API call | `2` | ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | --------------------------------------------------- | | 400 | No | Website is unreachable | | 404 | Yes | No company data could be extracted from the website | ## Employee Count Endpoint `GET /api/v1/company/employee-count` Cost: `2` credits / successful request. Retrieve the employee count range for a company given its website URL. ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "website=https://www.stripe.com" \ "https://nubela.co/api/v1/company/employee-count" ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.CompanyAPIApi(api_client) response = api.get_employee_count(website="https://www.stripe.com") print(response) ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; defaultClient.authentications["bearerAuth"].accessToken = "YOUR_API_KEY"; var api = new NinjaPear.CompanyAPIApi(); api.getEmployeeCount("https://www.stripe.com").then(function (data) { console.log(data); }); ``` > Example response: ```json { "employee_count": 3500 } ``` ### URL Parameters | Parameter | Required | Description | Example | | --------- | -------- | ------------------------------------- | ------------------------ | | `website` | Yes | The website URL of the target company | `https://www.stripe.com` | ### Response | Key | Description | Example | | ---------------- | ------------------------ | ------- | | `employee_count` | Estimated employee count | `3500` | ### Response Headers | Header Key | Description | Example | | ------------------------- | --------------------------------------- | ------- | | `X-NinjaPear-Credit-Cost` | Total cost of credits for this API call | `2` | ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | -------------------------------------------------- | | 404 | No | No employee count data found for the given website | ## Company Updates Endpoint `GET /api/v1/company/updates` Cost: `2` credits / request. Retrieve the latest blog posts and X/Twitter updates for a company. Returns a mixed timeline of recent blog and X posts sorted by timestamp. ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "website=https://www.stripe.com" \ "https://nubela.co/api/v1/company/updates" ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.CompanyAPIApi(api_client) response = api.get_company_updates(website="https://www.stripe.com") print(response) ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; defaultClient.authentications["bearerAuth"].accessToken = "YOUR_API_KEY"; var api = new NinjaPear.CompanyAPIApi(); api.getCompanyUpdates("https://www.stripe.com").then(function (data) { console.log(data); }); ``` > Example response ```json { "blogs": ["https://stripe.com/blog/feed.rss"], "x_profile": "https://x.com/stripe", "updates": [ { "url": "https://stripe.com/blog/annual-letter-2024", "title": "Stripe's annual letter", "description": "A look back at what we built in 2024 and what's ahead.", "image_url": null, "timestamp": "2025-03-01T12:00:00+00:00", "source": "blog" }, { "url": "https://x.com/stripe/status/1234567890", "title": "We just launched a new feature...", "description": "We just launched a new feature that makes payments even easier. Check it out!", "image_url": "https://pbs.twimg.com/media/example.jpg", "timestamp": "2025-02-28T18:30:00+00:00", "source": "x" } ], "timestamp": "2025-03-16T10:00:00+00:00" } ``` ### URL Parameters | Parameter | Required | Description | Example | | --------- | -------- | ------------------------------------- | ------------------------ | | `website` | Yes | The website URL of the target company | `https://www.stripe.com` | ### Response | Key | Description | Example | | ----------- | ------------------------------------------------------------------------------------- | -------------------------------------- | | `blogs` | List of blog RSS feed URLs (if RSS was discovered) or blog page URLs | `["https://stripe.com/blog/feed.rss"]` | | `x_profile` | X/Twitter profile URL, or `null` if not found | `"https://x.com/stripe"` | | `updates` | List of update objects (blog posts and tweets mixed), sorted by timestamp descending. | See [Update Object](#update-object) | | `timestamp` | UTC timestamp of when this data was pulled | `"2025-03-16T10:00:00+00:00"` | ### Update Object | Key | Description | Example | | ------------- | ---------------------------------------------------------- | ------------------------------------------- | | `url` | URL of the blog post or tweet | `"https://stripe.com/blog/example"` | | `title` | Title of the post (first 80 chars for tweets) | `"Stripe's annual letter"` | | `description` | Post description or tweet text (up to 500 chars for blogs) | `"A look back at..."` | | `image_url` | Image URL (tweet media), or `null` | `"https://pbs.twimg.com/media/example.jpg"` | | `timestamp` | ISO 8601 publication timestamp, or `null` if unknown | `"2025-03-01T12:00:00+00:00"` | | `source` | Source type of the update | `"blog"` or `"x"` | ### Response Headers | Header Key | Description | Example | | ------------------------- | --------------------------------------- | ------- | | `X-NinjaPear-Credit-Cost` | Total cost of credits for this API call | `2` | ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | ------------------------------------ | | 400 | No | Missing or invalid website parameter | | 403 | No | Insufficient credits | ## Company Funding Endpoint `GET /api/v1/company/funding` Cost: `2` credits / request (base) + `1` credit per unique investor returned. Base credits are charged even if no funding data is found (404). Retrieve funding history for a company given its website URL. Returns total funds raised, individual funding rounds with dates and amounts, and participating investors with their websites. ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "website=https://www.stripe.com" \ "https://nubela.co/api/v1/company/funding" ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.CompanyAPIApi(api_client) response = api.get_company_funding(website="https://www.stripe.com") print(response) ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; defaultClient.authentications["bearerAuth"].accessToken = "YOUR_API_KEY"; var api = new NinjaPear.CompanyAPIApi(); api.getCompanyFunding("https://www.stripe.com").then(function (data) { console.log(data); }); ``` > Example response ```json { "total_funds_raised_usd": 9810000000, "funding_rounds": [ { "round_type": "SECONDARY_SALE", "date": "2026-02-01", "amount_usd": null, "investors": [ { "name": "Thrive Capital", "website": "thrivecap.com", "type": "company", "amount_usd": null }, { "name": "Coatue", "website": "coatue.com", "type": "company", "amount_usd": null }, { "name": "Andreessen Horowitz", "website": "a16z.com", "type": "company", "amount_usd": null } ] }, { "round_type": "SERIES_I", "date": "2024-04-01", "amount_usd": 694200000, "investors": [ { "name": "Sequoia Capital", "website": "sequoiacap.com", "type": "company", "amount_usd": null }, { "name": "Brookfield", "website": "brookfield.com", "type": "company", "amount_usd": null }, { "name": "Paradigm", "website": "paradigm.co", "type": "company", "amount_usd": null } ] }, { "round_type": "SERIES_I", "date": "2023-03-01", "amount_usd": 6500000000, "investors": [ { "name": "GIC", "website": "gic.com.sg", "type": "company", "amount_usd": null }, { "name": "Goldman Sachs", "website": "goldmansachs.com", "type": "company", "amount_usd": null }, { "name": "Temasek", "website": "temasek.com.sg", "type": "company", "amount_usd": null }, { "name": "Thrive Capital", "website": "thrivecap.com", "type": "company", "amount_usd": null } ] }, { "round_type": "SERIES_H", "date": "2021-03-01", "amount_usd": 600000000, "investors": [ { "name": "Allianz X", "website": "allianzx.com", "type": "company", "amount_usd": null }, { "name": "Fidelity", "website": "fidelity.com", "type": "company", "amount_usd": null }, { "name": "Baillie Gifford", "website": "bailliegifford.com", "type": "company", "amount_usd": null } ] }, { "round_type": "SEED", "date": "2011-03-01", "amount_usd": 2000000, "investors": [ { "name": "Peter Thiel", "website": null, "type": "angel", "amount_usd": null }, { "name": "Sequoia Capital", "website": "sequoiacap.com", "type": "company", "amount_usd": null }, { "name": "Elon Musk", "website": null, "type": "angel", "amount_usd": null } ] } ] } ``` ### URL Parameters | Parameter | Required | Description | Example | | --------- | -------- | ------------------------------------- | ------------------------ | | `website` | Yes | The website URL of the target company | `https://www.stripe.com` | ### Response | Key | Description | Example | | ------------------------ | -------------------------------------------------------- | ------------ | | `total_funds_raised_usd` | Total funding raised in USD, or `null` if undisclosed | `9810000000` | | `funding_rounds` | Array of FundingRound objects, sorted by date descending | See below | ### FundingRound Object | Key | Description | Example | | ------------ | -------------------------------------------------------------- | -------------- | | `round_type` | Type of funding round (see round type values below) | `"SERIES_A"` | | `date` | Date of the round in `YYYY-MM-DD` format, or `null` if unknown | `"2023-03-01"` | | `amount_usd` | Amount raised in this round in USD, or `null` if undisclosed | `600000000` | | `investors` | Array of Investor objects that participated in this round | See below | ### Investor Object | Key | Description | Example | | ------------ | ----------------------------------------------------------------------- | ------------------- | | `name` | Name of the investor (firm or individual) | `"Sequoia Capital"` | | `website` | Website domain of the investor, or `null` if unknown | `"sequoiacap.com"` | | `type` | Either `"company"` (VC firm, fund, corporate) or `"angel"` (individual) | `"company"` | | `amount_usd` | Amount this investor contributed in USD, or `null` if undisclosed | `null` | ### Round Type Values `PRE_SEED`, `SEED`, `SERIES_A`, `SERIES_B`, `SERIES_C`, `SERIES_D`, `SERIES_E`, `SERIES_F`, `SERIES_G`, `SERIES_H`, `SERIES_I` through `SERIES_Z`, `BRIDGE`, `VENTURE_DEBT`, `CONVERTIBLE_NOTE`, `GRANT`, `SECONDARY_SALE`, `PRIVATE_EQUITY`, `GROWTH_EQUITY`, `IPO`, `POST_IPO_EQUITY`, `POST_IPO_DEBT`, `DEBT_FINANCING`, `CROWDFUNDING`, `CORPORATE_ROUND`, `UNKNOWN` ### Response Headers | Header Key | Description | Example | | ------------------------- | ----------------------------------------------------------------- | ------- | | `X-NinjaPear-Credit-Cost` | Total cost of credits for this API call (2 base + 1 per investor) | `7` | ### Error Codes | Status Code | Charged? | Description | | ----------- | --------------- | ------------------------------------------- | | 400 | No | Missing or invalid website parameter | | 403 | No | Insufficient credits | | 404 | Yes (2 credits) | No funding data found for the given website | # Employee API ## Person Profile Endpoint `GET /api/v1/employee/profile` Cost: `3` credits / request. Credits are charged even if no data is found. Enrich an employee's professional profile given a work email address, or a name and employer combination. Returns structured profile data including work history, education, location, and social media presence. You must provide at least one of these input combinations: - **Work email only** — e.g. `work_email=john@stripe.com` - **First name + employer website** — e.g. `first_name=John&employer_website=https://stripe.com` - **Employer website + role** — e.g. `employer_website=https://stripe.com&role=CTO` You can always add more parameters to improve accuracy. For example, providing `work_email` together with `first_name`, `last_name`, and `role` will yield better results than `work_email` alone. ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "work_email=john@stripe.com" \ "https://nubela.co/api/v1/employee/profile" ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.EmployeeAPIApi(api_client) profile = api.get_person_profile(work_email="john@stripe.com") print(profile) ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; defaultClient.authentications["bearerAuth"].accessToken = "YOUR_API_KEY"; var api = new NinjaPear.EmployeeAPIApi(); api.getPersonProfile({ workEmail: "john@stripe.com" }).then(function (data) { console.log(data); }); ``` > Example response ```json { "profile_pic_url": "https://pbs.twimg.com/profile_images/1234567890/photo_400x400.jpg", "first_name": "Elon", "middle_name": "Reeve", "last_name": "Musk", "full_name": "Elon Reeve Musk", "bio": "Mars & Cars, Chips & Dips", "follower_count": 195000000, "following_count": 782, "country": "US", "city": "USAUS", "state": "US-TX", "x_handle": "elonmusk", "x_profile_url": "https://x.com/elonmusk", "personal_website": "https://elonmusk.com", "work_experience": [ { "role": "CEO", "company_name": "Tesla", "company_website": "tesla.com", "description": "Leading Tesla's mission to accelerate the world's transition to sustainable energy.", "start_date": "2008-10", "end_date": null }, { "role": "CEO and CTO", "company_name": "SpaceX", "company_website": "spacex.com", "description": "Founded SpaceX with the goal of reducing space transportation costs and enabling the colonization of Mars.", "start_date": "2002-05", "end_date": null }, { "role": "Co-founder", "company_name": "PayPal", "company_website": "paypal.com", "description": null, "start_date": "1999-01", "end_date": "2002-10" } ], "education": [ { "major": "B.S. Economics", "school": "Wharton School, University of Pennsylvania", "start_date": "1992-01", "end_date": "1997-01" }, { "major": "B.S. Physics", "school": "University of Pennsylvania", "start_date": "1992-01", "end_date": "1997-01" } ], "similar_people": "https://nubela.co/api/v1/employee/similar?id=abc123de-f456-7890-abcd-ef1234567890" } ``` ### URL Parameters | Parameter | Required | Description | Example | | ------------------ | ----------- | -------------------------------------------------------------------------------------------------- | -------------------- | | `work_email` | Conditional | Work email address of the person. Required if `employer_website` is not provided. | `john@stripe.com` | | `first_name` | Conditional | Person's first name. Required when using name + `employer_website` combination. | `John` | | `middle_name` | No | Person's middle name. Improves accuracy when combined with other parameters. | `Michael` | | `last_name` | No | Person's last name. Improves accuracy when combined with other parameters. | `Smith` | | `employer_website` | Conditional | Website URL of the person's employer. Required if `work_email` is not provided. | `https://stripe.com` | | `role` | No | Current job title or role. Improves accuracy. Required when using `employer_website` without name. | `CTO` | ### Valid Input Combinations | Combination | Example | | --------------------------------- | ------------------------------------------------------ | | `work_email` alone | `?work_email=john@stripe.com` | | `first_name` + `employer_website` | `?first_name=John&employer_website=https://stripe.com` | | `employer_website` + `role` | `?employer_website=https://stripe.com&role=CTO` | Additional parameters can always be included to improve result accuracy. ### Response | Key | Description | Example | | ------------------ | -------------------------------------------------------------------------------- | --------------------------------------------------- | | `profile_pic_url` | URL to the person's profile picture (from X/Twitter). May be `null`. | `"https://pbs.twimg.com/.../photo_400x400.jpg"` | | `first_name` | First name | `"Elon"` | | `middle_name` | Middle name. May be `null`. | `"Reeve"` | | `last_name` | Last name | `"Musk"` | | `full_name` | Full name | `"Elon Reeve Musk"` | | `bio` | Bio/description from X/Twitter profile. May be `null`. | `"Mars & Cars, Chips & Dips"` | | `follower_count` | Number of X/Twitter followers. May be `null`. | `195000000` | | `following_count` | Number of X/Twitter accounts followed. May be `null`. | `782` | | `country` | Country of residence. ISO 3166-1 alpha-2 code. | `"US"` | | `city` | City of residence. UN/LOCODE. | `"USAUS"` | | `state` | State or region of residence. ISO 3166-2 subdivision code. | `"US-TX"` | | `x_handle` | X/Twitter handle (without @). May be `null`. | `"elonmusk"` | | `x_profile_url` | URL to X/Twitter profile. May be `null`. | `"https://x.com/elonmusk"` | | `personal_website` | Personal website URL. May be `null`. | `"https://elonmusk.com"` | | `work_experience` | List of work history entries, most recent first | \[[WorkExperience Object](#workexperience-object)\] | | `education` | List of education entries, most recent first | \[[Education Object](#education-object)\] | | `similar_people` | Pre-built URL to the [Similar People Endpoint](#similar-people-endpoint) for this person, keyed by their `id`. Call it directly to fetch people with the same role at competing companies — no need to re-pass search params. | `"https://nubela.co/api/v1/employee/similar?id=abc123de-..."` | ### WorkExperience Object | Key | Description | Example | | ----------------- | ---------------------------------------------------------------- | ------------------------------ | | `role` | Job title or role | `"CEO"` | | `company_name` | Name of the company | `"Tesla"` | | `company_website` | Company website domain. May be `null`. | `"tesla.com"` | | `description` | Description of what the person did in this role. May be `null`. | `"Leading Tesla's mission..."` | | `start_date` | Start date in YYYY-MM format. May be `null`. | `"2008-10"` | | `end_date` | End date in YYYY-MM format. `null` means currently in this role. | `null` | ### Education Object | Key | Description | Example | | ------------ | -------------------------------------------- | ---------------------------------------------- | | `major` | Degree and field of study | `"B.S. Economics"` | | `school` | School or university name | `"Wharton School, University of Pennsylvania"` | | `start_date` | Start date in YYYY-MM format. May be `null`. | `"1992-01"` | | `end_date` | End date in YYYY-MM format. May be `null`. | `"1997-01"` | ### Response Headers | Header Key | Description | Example | | ------------------------- | --------------------------------------- | ------- | | `X-NinjaPear-Credit-Cost` | Total cost of credits for this API call | `3` | ### Error Codes | Status Code | Charged? | Description | | -------------------- | --------------- | --------------------------------------------------------------------------------------------------------------- | | 400 | No | Invalid input. Must provide `work_email`, or `first_name` + `employer_website`, or `employer_website` + `role`. | | 403 | No | Insufficient credits | | 404 | Yes (3 credits) | No profile data could be found for the given input | | 503 | No | Service temporarily unavailable (AI Mode or LLM provider failed). Retry later. | ## Similar People Endpoint `GET /api/v1/employee/similar` Cost: `10` credits base + `5` credits per (company, role) tuple attempted. The base cost is charged regardless of whether any similar people are found, because the endpoint expends real-time scraping resources to fulfil every request. Cached results are free (see below). Find people who are *similar* to a target person — defined as people holding the **same role at competing companies**. Given a target (e.g. the CEO of `nubela.co`), the endpoint identifies the target's current employer, looks up that employer's competitors, and attempts to enrich the same-role person at each competitor in real time. The response returns the target's profile, the list of (company, role) tuples we attempted to search, and the similar people we successfully enriched. Inputs are identical to the [Person Profile Endpoint](#person-profile-endpoint). You must provide at least one of these input combinations: - **Work email only** — e.g. `work_email=tim@apple.com` - **First name + employer website** — e.g. `first_name=Tim&employer_website=https://apple.com` - **Employer website + role** — e.g. `employer_website=https://apple.com&role=CEO` ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ --max-time 300 \ --data-urlencode "work_email=tim@apple.com" \ "https://nubela.co/api/v1/employee/similar" ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.EmployeeAPIApi(api_client) # Set a generous read timeout — calls can take up to 5 minutes. result = api.get_similar_people(work_email="tim@apple.com", _request_timeout=300) print(result) ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; defaultClient.authentications["bearerAuth"].accessToken = "YOUR_API_KEY"; defaultClient.timeout = 300000; // 5 minutes var api = new NinjaPear.EmployeeAPIApi(); api.getSimilarPeople({ workEmail: "tim@apple.com" }).then(function (data) { console.log(data); }); ``` > Example response ```json { "target": { "first_name": "Tim", "last_name": "Cook", "full_name": "Tim Cook", "work_experience": [ { "role": "CEO", "company_name": "Apple", "company_website": "apple.com", "start_date": "2011-08", "end_date": null } ] }, "attempted_searches": [ { "employer_website": "samsung.com", "role": "CEO" }, { "employer_website": "google.com", "role": "CEO" }, { "employer_website": "microsoft.com", "role": "CEO" }, { "employer_website": "huawei.com", "role": "CEO" } ], "similar_people": [ { "first_name": "Sundar", "last_name": "Pichai", "full_name": "Sundar Pichai", "work_experience": [ { "role": "CEO", "company_name": "Google", "company_website": "google.com", "start_date": "2015-08", "end_date": null } ] }, { "first_name": "Satya", "last_name": "Nadella", "full_name": "Satya Nadella", "work_experience": [ { "role": "CEO", "company_name": "Microsoft", "company_website": "microsoft.com", "start_date": "2014-02", "end_date": null } ] } ], "credit_cost": 30 } ``` For brevity the example above shows only a subset of `PersonProfile` fields. Each entry under `target` and `similar_people` is a full `PersonProfile` object — see the [Person Profile Endpoint Response](#response-3) for the complete schema, including `profile_pic_url`, `bio`, `country`, `x_handle`, `education`, etc. ### URL Parameters Identical to the [Person Profile Endpoint URL Parameters](#url-parameters-7). | Parameter | Required | Description | Example | | ------------------ | ----------- | -------------------------------------------------------------------------------------------------- | -------------------- | | `work_email` | Conditional | Work email address of the target person. Required if `employer_website` is not provided. | `tim@apple.com` | | `first_name` | Conditional | Target's first name. Required when using name + `employer_website` combination. | `Tim` | | `middle_name` | No | Target's middle name. Improves accuracy when combined with other parameters. | `Donald` | | `last_name` | No | Target's last name. Improves accuracy when combined with other parameters. | `Cook` | | `employer_website` | Conditional | Website URL of the target's employer. Required if `work_email` is not provided. | `https://apple.com` | | `role` | No | Current job title or role. Required when using `employer_website` without name. | `CEO` | ### Valid Input Combinations | Combination | Example | | --------------------------------- | ----------------------------------------------------- | | `work_email` alone | `?work_email=tim@apple.com` | | `first_name` + `employer_website` | `?first_name=Tim&employer_website=https://apple.com` | | `employer_website` + `role` | `?employer_website=https://apple.com&role=CEO` | ### Response | Key | Description | Example | | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------ | | `target` | The resolved target person's full profile. Same schema as the [Person Profile Endpoint](#person-profile-endpoint). | `{ "first_name": "Tim", ... }` | | `attempted_searches` | List of (company, role) tuples we attempted to enrich. One entry per competitor of the target's current employer. Drives the per-tuple billing (5 credits each). | \[[AttemptedSearch Object](#attemptedsearch-object)\] | | `similar_people` | List of successfully enriched profiles for people matching the same role at competing companies. May be a subset of `attempted_searches` (some attempts return no data). Each entry uses the same schema as the [Person Profile Endpoint](#person-profile-endpoint). | \[PersonProfile, ...\] | | `credit_cost` | Total credits charged for this call. Equal to `10 + 5 * len(attempted_searches)`, or `0` for cached results served to the same product that previously paid. | `30` | ### AttemptedSearch Object | Key | Description | Example | | ------------------ | ---------------------------------------------------------- | --------------- | | `employer_website` | Competitor company website domain that we attempted. | `"google.com"` | | `role` | Role we searched for at that competitor (mirrors target). | `"CEO"` | ### Response Headers This endpoint streams its response, so the credit cost cannot be returned in a header — HTTP trailers aren't supported by the streaming layer. Read the `credit_cost` field on the response body instead of the usual `X-NinjaPear-Credit-Cost` header. ### Error Codes | Status Code | Charged? | Description | | ----------- | ---------------- | --------------------------------------------------------------------------------------------------------------- | | 400 | No | Invalid input. Must provide `work_email`, or `first_name` + `employer_website`, or `employer_website` + `role`. | | 403 | No | Insufficient credits. You need at least 10 credits to start a similar-people search. | | 404 | No | Target person could not be resolved. | | 503 | No | Resource temporarily unavailable. Please try again. | # Meta API ## View Credit Balance Endpoint `GET /api/v1/meta/credit-balance` Cost: `0` credit / successful request. Get your current credit balance. ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://nubela.co/api/v1/meta/credit-balance" ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.MetaAPIApi(api_client) response = api.get_credit_balance() print(response) ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; defaultClient.authentications["bearerAuth"].accessToken = "YOUR_API_KEY"; var api = new NinjaPear.MetaAPIApi(); api.getCreditBalance().then(function (data) { console.log(data); }); ``` > Example response: ```json { "credit_balance": 100000 } ``` ### Response | Key | Description | Example | | ---------------- | --------------------------- | -------- | | `credit_balance` | Your current credit balance | `100000` | ### Response Headers | Header Key | Description | Example | | ------------------------- | --------------------------------------- | ------- | | `X-NinjaPear-Credit-Cost` | Total cost of credits for this API call | `0` | ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | --------------- | | 401 | No | Invalid API key | # Contact API ## Disposable Email Checker Endpoint `GET /api/v1/contact/disposable-email` Cost: `0` credit / successful request. (FREE) Check if an email address is a disposable (temporary/throwaway) email or a free email provider. ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ --data-urlencode "email=test@mailinator.com" \ "https://nubela.co/api/v1/contact/disposable-email" ``` ```python import ninjapear configuration = ninjapear.Configuration( host="https://nubela.co", access_token="YOUR_API_KEY" ) with ninjapear.ApiClient(configuration) as api_client: api = ninjapear.ContactAPIApi(api_client) response = api.check_disposable_email(email="test@mailinator.com") print(response) ``` ```javascript var NinjaPear = require("ninjapear"); var defaultClient = NinjaPear.ApiClient.instance; defaultClient.authentications["bearerAuth"].accessToken = "YOUR_API_KEY"; var api = new NinjaPear.ContactAPIApi(); api.checkDisposableEmail("test@mailinator.com").then(function (data) { console.log(data); }); ``` > Example response: ```json { "email": "test@mailinator.com", "is_disposable_email": true, "is_free_email": false } ``` ### URL Parameters | Parameter | Required | Description | Example | | --------- | -------- | -------------------------- | --------------------- | | `email` | Yes | The email address to check | `test@mailinator.com` | ### Response | Key | Description | Example | | --------------------- | ------------------------------------------------------------------------------ | ----------------------- | | `email` | The email address that was checked | `"test@mailinator.com"` | | `is_disposable_email` | Whether the email domain is a known disposable/temporary email provider | `true` | | `is_free_email` | Whether the email domain is a free email provider (e.g., gmail.com, yahoo.com) | `false` | ### Response Headers | Header Key | Description | Example | | ------------------------- | --------------------------------------- | ------- | | `X-NinjaPear-Credit-Cost` | Total cost of credits for this API call | `0` | ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | -------------------- | | 400 | No | Invalid email format | # Monitor API The Monitor API allows you to monitor updates of companies. Every new update is compiled into a single RSS feed. The system monitors company blogs, X (Twitter) profiles, and website changes. ## Core Concepts - **Feed:** The parent container. A feed can be public or private. Private feeds require a bearer token passed via the URL query string to ensure compatibility with standard RSS readers. - **Target:** A specific company/website being monitored within a feed. - **Settings:** Granular preferences per target dictating what to monitor (Blog, X, Website) and how often. ## How To Use Suppose you want to monitor a group of competitor websites for blog posts, X activity, and website changes — all delivered as a single RSS feed you can plug into Feedly, Slack, Zapier, or any RSS reader. **1. Create a feed with targets** — group the companies you want to monitor into a feed. Each company is a **target** identified by its website URL.
curl -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "SaaS Competitors", "targets": [ { "website_url": "https://stripe.com" }, { "website_url": "https://shopify.com" }, { "website_url": "https://vercel.com" } ] }' \ "https://nubela.co/api/v1/monitor/feeds"
The response includes an `rss_url` — this is the URL you subscribe to.
{ "id": "feed_abc123", "rss_url": "https://nubela.co/.../rss.xml?token=sec_live_..." }
**2. Subscribe to the RSS feed** — copy the `rss_url` and add it to any RSS reader (Feedly, Slack, Zapier, etc.). Blog posts, X posts, and website changes from all targets appear as items in a single feed.
Stripe: Expanding our Payment Network [blog] Vercel on X: "Next.js 16 is here" [x] Shopify: Pricing Page [website update]
Each item includes a category (`blog`, `x`, `website update`, or `website new page`). See [Consume Feed Endpoint](#consume-feed-endpoint) for the full RSS schema. **3. Add new targets** — a new competitor entered the market? Add them to the feed.
curl -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "website_url": "https://linear.app" }' \ "https://nubela.co/api/v1/monitor/feeds/feed_abc123/targets"
**4. Remove targets** — a company is no longer relevant? Remove it from the feed.
curl -X DELETE \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://nubela.co/api/v1/monitor/feeds/feed_abc123/targets/target_xyz789"
**5. Change monitoring settings** — by default every target monitors blog posts, X posts, and website changes on a 7-day cadence. Use PATCH to toggle channels or change the frequency.
curl -X PATCH \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "settings": { "monitor_x": false, "frequency_days": 1 } }' \ "https://nubela.co/api/v1/monitor/feeds/feed_abc123/targets/target_xyz789"
Only the fields you include are changed — omitted fields keep their current values. See [Settings Object](#settings-object) for all available options. ## Pricing | Action | Cost | | ------------------------------------------------------------------ | -------------------- | | Create a feed | 3 credits (one-time) | | Blog post pull (per target) | 1 credit/pull | | Website monitoring pull (per target) | 1 credit/pull | | X post updates pull (per target) | 2 credits/pull | | All other endpoints (list, describe, delete feeds; manage targets) | 0 credits | Each pull checks one target for one source (blog, X, or website). With all three sources enabled, a single target costs **4 credits per pull** (1 blog + 2 X + 1 website). ### Example monthly costs | Scenario | Targets | Frequency | Credits/month | | ------------------------------------------------------------------- | ------- | --------- | -------------------------------------------------- | | VC tracking 20 portfolio companies | 20 | Weekly | ~**346** credits (3 one-time + 20 × 4 × 4.3 weeks) | | Startup monitoring 10 competitors | 10 | Daily | ~**1,203** credits (3 one-time + 10 × 4 × 30 days) | | Sales team watching 5 prospect accounts (blog + X only, no website) | 5 | Daily | ~**453** credits (3 one-time + 5 × 3 × 30 days) | One-time feed creation cost (3 credits) is included in the first month only. ## List Feeds Endpoint `GET /api/v1/monitor/feeds` Cost: `0` credits / request. Retrieves a list of all feeds owned by the authenticated user. ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://nubela.co/api/v1/monitor/feeds" ``` > Example response: ```json { "feeds": [ { "id": "feed_abc123", "name": "SaaS Competitors", "is_public": false, "rss_url": "https://nubela.co/api/v1/monitor/feeds/feed_abc123/rss.xml?token=sec_live_987654321", "created_at": "2026-02-24T00:00:00Z", "target_count": 2 } ] } ``` ### Response | Key | Description | Example | | ------- | -------------------- | ------------------------------- | | `feeds` | List of Feed objects | See [Feed Object](#feed-object) | ### Feed Object | Key | Description | Example | | --------------------- | ---------------------------------------------------------------------- | --------------------------------------------------------------------------------------- | | `id` | Unique feed identifier | `"feed_abc123"` | | `name` | Feed name | `"SaaS Competitors"` | | `is_public` | Whether the feed is publicly accessible | `false` | | `is_suspended` | Whether the feed is currently suspended | `false` | | `suspension_reason` | Reason for suspension, if suspended | `null` or `"insufficient_credits"` | | `rss_url` | The RSS feed URL. For private feeds, includes a token query parameter. | `"https://nubela.co/api/v1/monitor/feeds/feed_abc123/rss.xml?token=sec_live_987654321"` | | `email_notifications` | Email notification mode | `"skip"` or `"on_updates"` | | `created_at` | ISO 8601 creation timestamp | `"2026-02-24T00:00:00Z"` | | `target_count` | Number of targets in the feed | `2` | ## New Feed Endpoint `POST /api/v1/monitor/feeds` Cost: `3` credits / request (one-time fee). Creates a new feed and optionally accepts an array of initial targets. ```shell curl -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "SaaS Competitors", "is_public": false, "targets": [ { "website_url": "https://stripe.com", "settings": { "monitor_blog": true, "monitor_x": true, "monitor_website": true, "frequency_days": 7 } }, { "website_url": "https://vercel.com" } ] }' \ "https://nubela.co/api/v1/monitor/feeds" ``` > Example response `201 Created`: ```json { "id": "feed_abc123", "name": "SaaS Competitors", "is_public": false, "is_suspended": false, "suspension_reason": null, "rss_url": "https://nubela.co/api/v1/monitor/feeds/feed_abc123/rss.xml?token=sec_live_987654321", "created_at": "2026-02-24T09:55:00Z", "targets": [ { "id": "target_xyz789", "website_url": "https://stripe.com", "settings": { "monitor_blog": true, "monitor_x": true, "monitor_website": true, "frequency_days": 7 }, "last_polled_at": null, "is_baseline_complete": false, "created_at": "2026-02-24T09:55:00Z" }, { "id": "target_xyz790", "website_url": "https://vercel.com", "settings": { "monitor_blog": true, "monitor_x": true, "monitor_website": true, "frequency_days": 7 }, "last_polled_at": null, "is_baseline_complete": false, "created_at": "2026-02-24T09:55:00Z" } ] } ``` ### Request Body | Parameter | Required | Description | Example | | --------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------- | | `name` | No | Name of the feed. If omitted, a name will be auto-generated. | `"SaaS Competitors"` | | `is_public` | No | Whether the feed is publicly accessible (default: `false`) | `false` | | `email_notifications` | No | Email notification mode. `"on_updates"` to receive emails when new updates are detected, `"skip"` to disable (default: `"skip"`) | `"on_updates"` | | `targets` | Yes | Array of initial targets to add to the feed (at least 1 required) | See [Target Input Object](#target-input-object) | ### Target Input Object | Parameter | Required | Description | Example | | ------------- | -------- | --------------------------------------------------- | --------------------------------------- | | `website_url` | Yes | The website URL of the company to monitor | `"https://stripe.com"` | | `settings` | No | Monitoring preferences. If omitted, defaults apply. | See [Settings Object](#settings-object) | ### Settings Object | Parameter | Required | Description | Example | | ----------------- | -------- | --------------------------------------------------------------------------------- | ------- | | `monitor_blog` | No | Monitor the company's blog for new posts (default: `true`) | `true` | | `monitor_x` | No | Monitor the company's X (Twitter) account (default: `true`) | `true` | | `monitor_website` | No | Monitor the company's website for content changes and new pages (default: `true`) | `true` | | `frequency_days` | No | How often to check for updates, in days. Must be between 1 and 30 (default: `7`) | `7` | ### Validation Rules - At least one `targets` entry is required. - Each target must have a `website_url` that is reachable (HTTP 2xx response). Unreachable URLs return `400`. - At least one monitor setting (`monitor_blog`, `monitor_x`, `monitor_website`) must be `true` per target. ### Response Returns `201 Created`. The response includes the created [Feed Object](#feed-object) with an additional `targets` array containing [Target Object](#target-object) entries. ### Target Object | Key | Description | Example | | ---------------------- | -------------------------------------------------------------- | --------------------------------------- | | `id` | Unique target identifier | `"target_xyz789"` | | `website_url` | The monitored company's website URL | `"https://stripe.com"` | | `settings` | Monitoring preferences object | See [Settings Object](#settings-object) | | `last_polled_at` | ISO 8601 timestamp of the last poll, or `null` if never polled | `null` | | `is_baseline_complete` | Whether the initial baseline snapshot has been captured | `false` | | `created_at` | ISO 8601 creation timestamp | `"2026-02-24T09:55:00Z"` | ### Response Headers | Header Key | Description | Example | | ------------------------- | --------------------------------------- | ------- | | `X-NinjaPear-Credit-Cost` | Total cost of credits for this API call | `3` | ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | ----------------------------------------------------------------------------- | | 400 | No | Validation error (missing targets, unreachable URL, no monitor flags enabled) | ## Describe Feed Endpoint `GET /api/v1/monitor/feeds/{feed_id}` Cost: `0` credits / request. Retrieves full details of a single feed, including all its attached targets. ```shell curl -G \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://nubela.co/api/v1/monitor/feeds/feed_abc123" ``` > Example response: ```json { "id": "feed_abc123", "name": "SaaS Competitors", "is_public": false, "is_suspended": false, "suspension_reason": null, "rss_url": "https://nubela.co/api/v1/monitor/feeds/feed_abc123/rss.xml?token=sec_live_987654321", "created_at": "2026-02-24T09:55:00Z", "targets": [ { "id": "target_xyz789", "website_url": "https://stripe.com", "settings": { "monitor_blog": true, "monitor_x": true, "monitor_website": true, "frequency_days": 7 }, "last_polled_at": "2026-02-24T12:00:00Z", "is_baseline_complete": true, "created_at": "2026-02-24T09:55:00Z" }, { "id": "target_xyz790", "website_url": "https://vercel.com", "settings": { "monitor_blog": true, "monitor_x": true, "monitor_website": true, "frequency_days": 7 }, "last_polled_at": null, "is_baseline_complete": false, "created_at": "2026-02-24T09:55:00Z" } ] } ``` ### URL Parameters | Parameter | Required | Description | Example | | --------- | -------- | ------------------ | ------------- | | `feed_id` | Yes | The ID of the feed | `feed_abc123` | ### Response Returns a [Feed Object](#feed-object) with an additional `targets` array containing [Target Object](#target-object) entries. ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | -------------- | | 404 | No | Feed not found | ## Delete Feed Endpoint `DELETE /api/v1/monitor/feeds/{feed_id}` Cost: `0` credits / request. Permanently deletes a feed and all associated targets. ```shell curl -X DELETE \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://nubela.co/api/v1/monitor/feeds/feed_abc123" ``` ### URL Parameters | Parameter | Required | Description | Example | | --------- | -------- | ---------------------------- | ------------- | | `feed_id` | Yes | The ID of the feed to delete | `feed_abc123` | ### Response Returns `200 OK` with a confirmation message. ```json { "message": "Feed deleted." } ``` ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | -------------- | | 404 | No | Feed not found | ## Add Target Endpoint `POST /api/v1/monitor/feeds/{feed_id}/targets` Cost: `0` credits / request. Adds a new company to an existing feed. ```shell curl -X POST \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "website_url": "https://shopify.com", "settings": { "monitor_blog": true, "monitor_x": true, "monitor_website": false, "frequency_days": 3 } }' \ "https://nubela.co/api/v1/monitor/feeds/feed_abc123/targets" ``` > Example response `201 Created`: ```json { "id": "target_xyz791", "website_url": "https://shopify.com", "settings": { "monitor_blog": true, "monitor_x": true, "monitor_website": false, "frequency_days": 3 }, "last_polled_at": null, "is_baseline_complete": false, "created_at": "2026-02-24T10:00:00Z" } ``` ### URL Parameters | Parameter | Required | Description | Example | | --------- | -------- | --------------------------------------- | ------------- | | `feed_id` | Yes | The ID of the feed to add the target to | `feed_abc123` | ### Request Body | Parameter | Required | Description | Example | | ------------- | -------- | --------------------------------------------------- | --------------------------------------- | | `website_url` | Yes | The website URL of the company to monitor | `"https://shopify.com"` | | `settings` | No | Monitoring preferences. If omitted, defaults apply. | See [Settings Object](#settings-object) | ### Response Returns a [Target Object](#target-object). ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | -------------- | | 404 | No | Feed not found | ## Update Target Endpoint `PATCH /api/v1/monitor/feeds/{feed_id}/targets/{target_id}` Cost: `0` credits / request. Modifies the monitoring preferences for a specific target. ```shell curl -X PATCH \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "settings": { "frequency_days": 1, "monitor_website": true } }' \ "https://nubela.co/api/v1/monitor/feeds/feed_abc123/targets/target_xyz789" ``` ### URL Parameters | Parameter | Required | Description | Example | | ----------- | -------- | ------------------------------ | --------------- | | `feed_id` | Yes | The ID of the feed | `feed_abc123` | | `target_id` | Yes | The ID of the target to update | `target_xyz789` | ### Request Body | Parameter | Required | Description | Example | | ---------- | -------- | ---------------------------------------------------------- | --------------------------------------- | | `settings` | Yes | Partial settings update. Only provided fields are changed. | See [Settings Object](#settings-object) | ### Response Returns the updated [Target Object](#target-object). > Example response: ```json { "id": "target_xyz789", "website_url": "https://stripe.com", "settings": { "monitor_blog": true, "monitor_x": true, "monitor_website": true, "frequency_days": 1 }, "last_polled_at": "2026-02-24T12:00:00Z", "is_baseline_complete": true, "created_at": "2026-02-24T09:55:00Z" } ``` ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | -------------------------- | | 400 | No | No valid settings provided | | 404 | No | Feed or target not found | ## Remove Target Endpoint `DELETE /api/v1/monitor/feeds/{feed_id}/targets/{target_id}` Cost: `0` credits / request. Stops monitoring a website and removes it from the feed. ```shell curl -X DELETE \ -H "Authorization: Bearer YOUR_API_KEY" \ "https://nubela.co/api/v1/monitor/feeds/feed_abc123/targets/target_xyz789" ``` ### URL Parameters | Parameter | Required | Description | Example | | ----------- | -------- | ------------------------------ | --------------- | | `feed_id` | Yes | The ID of the feed | `feed_abc123` | | `target_id` | Yes | The ID of the target to remove | `target_xyz789` | ### Response Returns `200 OK` with a confirmation message. ```json { "message": "Target deleted." } ``` ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | ------------------------ | | 404 | No | Feed or target not found | ## Consume Feed Endpoint `GET /api/v1/monitor/feeds/{feed_id}/rss.xml` Cost: `0` credits / request (monitoring costs are incurred per-pull on each target — see [Pricing](#pricing)). Returns a standard RSS 2.0 XML feed consumed by RSS readers (Feedly, Slack, browser extensions, etc.). If the feed's `is_public` is `false`, a valid token must be passed as a `token` query parameter. ```shell curl "https://nubela.co/api/v1/monitor/feeds/feed_abc123/rss.xml?token=YOUR_RSS_TOKEN" ``` > Example response: ```xml SaaS Competitors https://nubela.co/api/v1/monitor/feeds/feed_abc123/rss.xml Automated updates for Stripe, Shopify, and Vercel. Tue, 24 Feb 2026 10:00:00 +0800 Stripe: Expanding our Global Payment Network https://stripe.com/blog/global-network-2026 https://stripe.com/blog/global-network-2026 Mon, 23 Feb 2026 14:30:00 +0800 blog Stripe Stripe is expanding its payments infrastructure to 15 new countries, enabling merchants to accept local payment methods seamlessly. Vercel on X: "Next.js 16 is here..." https://x.com/vercel/status/123456789 x_post_123456789 Sun, 22 Feb 2026 10:15:00 +0800 x Vercel Next.js 16 is here, featuring completely redesigned server components and faster builds. Read the changelog. Shopify: Pricing Page https://shopify.com/pricing website_update_shopify_pricing_1708416000 Fri, 20 Feb 2026 08:00:00 +0800 website update Shopify Compare Shopify's pricing plans to find the best fit for your business. Start your free trial today. Shopify: Enterprise Plus Solutions https://shopify.com/enterprise-plus https://shopify.com/enterprise-plus Thu, 19 Feb 2026 11:20:00 +0800 website new page Shopify Unleash your brand's potential with Shopify Enterprise Plus. High-volume solutions for global commerce. ``` ### URL Parameters | Parameter | Required | Description | Example | | --------- | -------- | ------------------ | ------------- | | `feed_id` | Yes | The ID of the feed | `feed_abc123` | ### Response Format The response is a standard RSS 2.0 XML document. The structure is as follows: ### Channel Elements | Element | Description | Example | | ----------------------- | --------------------------------------------- | ------------------------------------------------------------ | | `<title>` | The feed name | `SaaS Competitors` | | `<link>` | URL of the RSS feed | `https://nubela.co/api/v1/monitor/feeds/feed_abc123/rss.xml` | | `<description>` | Auto-generated summary of monitored companies | `Automated updates for Stripe, Shopify, and Vercel.` | | `<lastBuildDate>` | RFC 2822 timestamp of the last feed build | `Tue, 24 Feb 2026 10:00:00 +0800` | ### Item Elements Each `<item>` represents a single update from a monitored company. | Element | Description | Example | | --------------------- | ----------------------------------------------------------------------------------------- | ----------------------------------------------------------------- | | `<title>` | Update title, prefixed with the company name | `Stripe: Expanding our Global Payment Network` | | `<link>` | URL of the original content | `https://stripe.com/blog/global-network-2026` | | `<guid>` | Unique identifier for the item. `isPermaLink` is `true` when the GUID is a URL. | `https://stripe.com/blog/global-network-2026` | | `<pubDate>` | RFC 2822 publication timestamp | `Mon, 23 Feb 2026 14:30:00 +0800` | | `<category>` | Update type (see categories below) | `blog` | | `<dc:creator>` | Company name (uses Dublin Core namespace) | `Stripe` | | `<description>` | Summary or excerpt of the update | Text content | | `<enclosure>` | Optional image attachment with `url`, `length` (bytes), and `type` (MIME type) attributes | `<enclosure url="..." length="150000" type="image/jpeg" />` | ### RSS Item Categories Each `<item>` includes a `<category>` element indicating the update type: | Category | Description | | --------------------- | --------------------------------------------------------- | | `blog` | A new blog post from the company | | `x` | A post from the company's X (Twitter) account | | `website update` | A change detected on an existing page | | `website new page` | A new page detected on the company's website | | `website unreachable` | The company's website has become unreachable (fired once) | ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | ------------------------------------------- | | 403 | No | Missing or invalid token for a private feed | | 404 | No | Feed not found | ## Update Feed Endpoint `PATCH /api/v1/monitor/feeds/{feed_id}` Cost: `0` credits / request. Update feed settings such as name, visibility, or suspension status. Feeds suspended for `insufficient_credits` are automatically resumed when credits are added. ```shell # Suspend a feed curl -X PATCH \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "is_suspended": true, "suspension_reason": "manual" }' \ "https://nubela.co/api/v1/monitor/feeds/feed_abc123" ``` ```python import requests response = requests.patch( "https://nubela.co/api/v1/monitor/feeds/feed_abc123", headers={"Authorization": "Bearer YOUR_API_KEY"}, json={"is_suspended": True, "suspension_reason": "manual"}, ) ``` ```javascript const response = await fetch( "https://nubela.co/api/v1/monitor/feeds/feed_abc123", { method: "PATCH", headers: { Authorization: "Bearer YOUR_API_KEY", "Content-Type": "application/json", }, body: JSON.stringify({ is_suspended: true, suspension_reason: "manual" }), }, ); ``` > Example response (same as Describe Feed): ```json { "id": "feed_abc123", "name": "My Feed", "is_public": false, "is_suspended": true, "suspension_reason": "manual", "rss_url": "https://nubela.co/api/v1/monitor/feeds/feed_abc123/rss.xml?token=...", "created_at": "2025-01-15T10:30:00Z", "targets": [...] } ``` ### URL Parameters | Parameter | Required | Description | Example | | --------- | -------- | ------------------ | ------------- | | `feed_id` | Yes | The ID of the feed | `feed_abc123` | ### Request Body | Parameter | Required | Description | Example | | --------------------- | -------- | ------------------------------------------------------------------------------------------------------------ | -------------- | | `name` | No | New feed name | `"My Feed"` | | `is_public` | No | Whether the RSS feed is publicly accessible | `true` | | `is_suspended` | No | Set `true` to suspend, `false` to resume | `true` | | `suspension_reason` | No | Reason for suspension (only when `is_suspended` is `true`, default `"manual"`) | `"manual"` | | `email_notifications` | No | Email notification mode. `"on_updates"` to receive emails when new updates are detected, `"skip"` to disable | `"on_updates"` | At least one field must be provided. ### Response Returns the updated [Feed Object](#feed-object) with an additional `targets` array containing [Target Object](#target-object) entries. ### Error Codes | Status Code | Charged? | Description | | ----------- | -------- | ------------------------ | | 400 | No | No valid fields provided | | 404 | No | Feed not found | # Claude AI NinjaPear provides an MCP (Model Context Protocol) server for direct integration with Claude. This allows you to query B2B company data conversationally — ask Claude about any company's customers, investors, employee count, and more. ## Quick Start 1. Get your connector string from the [Dashboard](/dashboard/ai-integrations/claude) 2. Add NinjaPear as a connector in Claude (see setup instructions below) 3. Start a new conversation and query B2B company data conversationally ## Setup Your connector string is available on the [Dashboard](/dashboard/ai-integrations/claude). It looks like: `https://nubela.co/mcp/sse?api_key=YOUR_API_KEY` ### Claude Platform (Recommended) 1. Get your connector string from the [Dashboard](/dashboard/ai-integrations/claude) 2. Make sure you're logged into Claude, then visit: [Add Custom Connector](https://claude.ai/settings/connectors?modal=add-custom-connector) 3. Enter the following: - **Name**: `NinjaPear` - **Remote MCP server URL**: Paste your connector string from step 1 4. Click **Add connector** 5. Start a new conversation and ask Claude to use NinjaPear ### Claude Code CLI Get your connector string from the [Dashboard](/dashboard/ai-integrations/claude), then run: `claude mcp add ninjapear --transport sse "YOUR_CONNECTOR_STRING"` ## Available Tools | Tool | Description | Cost | | ------------------------ | --------------------------------------------------- | ------------- | | `get_customer_listing` | Get customers, investors, and partners of a company | 1 + 2/company | | `get_company_details` | Get company info, executives, financials | 2-4 credits | | `get_employee_count` | Get employee count for a company | 2 credits | | `check_disposable_email` | Check if email is disposable/free | FREE | | `get_credit_balance` | Check your credit balance | FREE | | `get_company_logo_url` | Get company logo URL | FREE | | `list_feeds` | List all your monitoring feeds | FREE | | `create_feed` | Create a new monitoring feed with targets | 3 credits | | `describe_feed` | Get feed details with all targets | FREE | | `update_feed` | Update feed name, visibility, or suspension | FREE | | `delete_feed` | Delete a feed and all its targets | FREE | | `add_target` | Add a company to monitor in a feed | FREE | | `update_target` | Update monitoring settings for a target | FREE | | `remove_target` | Remove a company from a feed | FREE | | `consume_feed` | Read the latest updates from a feed | FREE | ## Example Prompts Once connected, you can ask Claude questions like: **Competitive Intelligence** You're a product manager tracking what your competitors are up to. - "Monitor stripe.com, brex.com, and ramp.com for blog posts and website changes. Check daily." - "What are the latest updates from my competitor feed?" - "Get company details for each of my competitors — I want to know their employee counts and executives" - "Who are Stripe's customers? Cross-reference them with Brex's customers to find overlap" **VC Portfolio Monitoring** You're a VC who wants to stay on top of portfolio company activity. Upload a CSV or screenshot of your portfolio companies to Claude, then ask: - "Create a monitoring feed for all these companies — track their blogs and website changes weekly" - "Show me the latest updates across my portfolio feed" - "Get employee counts for each of my portfolio companies — I want to see who's growing fastest" - "Which of my portfolio companies have the most customers?" **Sales Prospecting** You're in sales and want to research accounts before outreach. - "Get company details for acme.com — who are their executives, and what industry are they in?" - "How many employees does acme.com have?" - "Who are Salesforce's customers? Get company details for the top 5 by employee count" - "Is john@acme.com a real business email or a disposable address?" - "Check if these emails are disposable: test@mailinator.com, jane@company.io" **Market Research** You're an analyst mapping out an industry landscape. - "Find the investors behind Figma, Canva, and Miro. Who are the common VCs?" - "Get company details for anthropic.com, openai.com, and cohere.com — compare their founding year, employee count, and specialties" - "Who are the partners of Shopify? Get employee counts for each partner" - "Get logos for stripe.com, square.com, and adyen.com — I'm building a market map" **Monitoring and Alerts** You want to set up ongoing monitoring and come back to check updates. - "Create a feed called 'AI Companies' to track openai.com, anthropic.com, and deepmind.google — monitor blogs and X posts" - "Add mistral.ai to my AI Companies feed" - "Change the monitoring frequency for Anthropic to daily — they ship fast" - "Pause my AI Companies feed for now, I'll resume it next quarter" - "What's my current credit balance? How long will my monitoring last at this rate?" **Account Management** Quick checks on your NinjaPear usage. - "What's my credit balance?" - "How many credits do I have left?" ## Error Handling Errors are returned as descriptive messages that Claude will explain to you: | Error | Message | | -------------------- | ---------------------------------- | | Invalid API key | "Error: 401 Unauthorized" | | Insufficient credits | "Error: 402 Payment Required" | | Rate limited | "Error: 429 Too Many Requests" | | Server error | "Error: 500 Internal Server Error" | ## Technical Details ### MCP Protocol The NinjaPear MCP server implements the [Model Context Protocol](https://modelcontextprotocol.io/) specification, which is Anthropic's open standard for connecting AI assistants to external data sources and tools. ### Transport We use Server-Sent Events (SSE) transport for real-time communication: - **SSE Endpoint**: `GET /mcp/sse?api_key=YOUR_API_KEY` - **Messages Endpoint**: `POST /mcp/messages/` - **Health Check**: `GET /mcp/health` ### Authentication Pass your API key via the `api_key` query parameter or the `X-API-Key` header