Use Cases & Examples
Copy-paste recipes for the jobs people build on aVenture data, in API, CLI, and MCP form
Each recipe answers one job with API, CLI, and MCP calls. Responses are abridged examples from a previous snapshot, not guarantees of current counts, roles, or funding totals. Resolve the record from its website or profile URL, then reuse its returned id. Data can change between calls. Create an account and finish the quickstart first.
The examples use Stripe (4eabfc26-3ed9-4ad3-a935-9be07ae3329a), Sequoia
Capital, and Patrick Collison. Swap in the ids returned by your own lookups.
For MCP JSON results, read the API body in data.response and check ok,
page metadata, and truncation warnings before drawing conclusions. For an
operation that offers both formats, set responseFormat: "json" when code
needs structured fields; auto may return text in data. The JSON below
shows the API body rather than the full MCP envelope. See
Call MCP tools directly.
Compact profile lookups may omit related rows or shorten research text. Page through the corresponding rounds, roles, or news sub-resource using the returned core.id before claiming complete coverage.
A successful lookup alone does not make its embedded lists complete.
Get a Company Brand Kit From Its Website
GET /v1/entities/brand takes any website or profile URL the company owns and
returns its brand and legal names, logo, current links, and current tags. The
lookup ignores the scheme, a leading www., and host case; a different path is
a different URL.
API
CLI
MCP
For a logo you can put in an <img> tag, read the logo slot with the core.id
from the first call. Its cdnUrl is a full image URL:
API
CLI
MCP
Each brand read counts one brand view per company per calendar month (UTC), on
an allowance separate from company profile views; reading the same company
again that month is free. A URL that two companies share answers 409 with the
candidate ids; send one of them as entityId. The
company brand lookup covers slug and id lookups,
errors, and each plan’s brand view allowance.
Match a List of Websites to Companies
POST /v1/entities/lookup-matches answers one row per input, in input order,
so you can join the answer back to a spreadsheet or CRM export. Each row’s
status is MATCHED, AMBIGUOUS, or MISSING.
API
CLI
MCP
An AMBIGUOUS row lists the records that share the URL in
candidateEntityId; read each by id to choose. The body also takes entityId
and slug arrays. Each matched record counts one profile view.
POST /v1/entities/lookup-batch takes the same body but returns only the
records it found, as a page, and drops the rest. To identify a bare name with no
URL, use Identify a company or person.
Build a Target List With Filters
Filters on the company list combine, and totalElements sizes the whole
market. This one finds seed-stage fintech companies headquartered in New York.
API
CLI
MCP
Read the current count from totalElements; size=3 returns only the first
page, not the whole market. Each row’s name and slug sit at content[].core.nameBrand and
content[].core.slug.
Filter values are case-sensitive display names: the tag is Fintech, and the
state is New York, not NY. GET /v1/entities/filters (CLI:
aventure entities filters list) lists every accepted value.
Pagination and filtering covers paging through the
full list.
For a plain-English discovery query, inspect the returned interpretation
before using its count. City and state are different filters, and a semantic
match for “fintech” is different from an exact industry or tag value.
Use explicit filter fields for hard requirements. Natural search puts its
paged records in result; a count-only typed search can return no rows while
totalElements remains positive.
Read a Funding History and the Investors in a Round
List the rounds newest first, then use the chosen round’s returned id as
transactionId to list its investors. Labels such as Series A can recur;
when the id is unknown, use round together with the exact dateAnnounced.
API
CLI
MCP
One recorded Series I round in the example snapshot:
Each investor row names the investor by id only, in investor.entityId or
investor.personId. Send several firm ids to the company list at once
(aventure entities search --entity-id <id> <id> --size 40) to read their names; for this
round they include General Catalyst, Thrive Capital, and Goldman Sachs Asset
Management. entityId is always the company that raised, never the investor.
Amounts stay in each round’s own currency; do not add different currencies without conversion.
A missing amount does not mean zero. Cumulative totals require complete, consistently denominated history.
List the Recent Portfolio of an Investor
Resolve the firm from its website, then list what it backed. A firm’s website can also belong to its fund records, so name the record type.
API
CLI
MCP
Read totalElements for the current portfolio count matching the date
filter. One example row, abridged:
latestPerEntity=true keeps one row per company. dateFrom and dateTo take
YYYY-MM-DD. For an angel investor, GET /v1/people/{personId}/investments
(CLI: aventure people investments list) lists the person’s investments. It has
no date or one-row-per-company filter, so sort it with sort=date,desc. The
reverse question, who backed one company, is
GET /v1/entities/{entityId}/investors.
Do not report amountRaised as the investor’s own contribution. Use
investorAttribution.amountInvested when present; if it is absent, the
individual contribution is unknown. Person investment rows use amount for
the round amount and date for the round date; retain the returned field
names when comparing them with other timestamps.
Trace Every Company a Founder Has Worked At
Resolve the person from a profile URL or slug, then list every role, current and past.
API
CLI
MCP
The role list is paginated; the abridged array below shows its content, not
the complete page. Fetch all pages before claiming to have every role.
The person lookup counts one person profile view; the role list does not.
GET /v1/entities/{entityId}/people answers the reverse question: who works at
one company.
Use the association’s titleName, isCurrent, startDate, and endDate
for that person’s role at that company. A person’s general bio can describe
a different company. Preserve date precision: a value such as 2010 is a
year, not proof of a January 1 start. Missing end dates do not establish a
current role; use isCurrent.
Find the Competitors of a Company
API
CLI
MCP
Each row pairs a company with why it is listed:
Stripe’s stored competitors include Block, Wise, and Visa. Without
relationshipType, the list ranks every similar company. This read is free on
every plan. To find companies that match a description instead of a known
company, use POST /v1/search/natural/entities (CLI:
aventure search natural entities --query "...").
For a question that needs evidence and an answer, request natural company
search layers passage, synthesis, judgment, and web. Keep the returned
record list, cited answer, and judgments separate: they can describe
different subsets. An answer citation names its source and sourceId; read
that source to inspect the supporting text. A retrieved peer or a similar
company is not automatically a stored competitor relationship. Check
truncation before treating passages or web-source lists as complete.
Read a Company’s Acquisitions
To read companies it bought, use listEntityAcquisitions with the company’s
returned id and query.role: "acquirer". The default acquired role asks
whether that company was bought; an empty default result does not mean it
made no acquisitions. all includes both sides. Keep the role fixed while
paging and distinguish acquisitions from investment rounds. Check status
and transactionStatus before saying a deal closed; an announced deal or one
subject to closing conditions is not a completed acquisition.
Monitor News About a Company
Ask for articles linked to a company since your last check, or let news alerts post each new article to your webhook.
API
CLI
MCP
Each article carries title, publication, publishedAt, excerpt, and
newsUrlOriginal, newest first. publishedAfter includes the date you send,
so store the date of each check and send it next time. Deduplicate overlapping
checks by article id and fetch all relevant pages before advancing the saved
date. The query key is the
dotted owner.entityId; owner.personId does the same for a person. Use one
owner selector at a time. An
article can mention the company in passing, so read its excerpt before you
alert on it. To start from an article instead, identify names in an
article finds every company and person it names.
Costs at a Glance
Plans and usage covers every allowance, and the API reference lists every parameter and response field.