Skip to navigation

Use Cases & Examples

Copy-paste recipes for the jobs people build on aVenture data, in API, CLI, and MCP form

View as Markdown

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.

You wantRecipe
A company’s name, logo, links, and tags from its websiteBrand kit from a website
Which company each website in a list belongs toMatch a list of websites
Every company that fits a market definitionTarget list
What a company raised and who investedFunding history
What a firm has backed latelyInvestor portfolio
A founder’s companies and rolesFounder background
A company’s competitorsCompetitors
New coverage of a companyNews monitoring

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.

curl -s -H "Authorization: Bearer $AUTH_TOKEN" \
"https://api.aventure.vc/v1/entities/brand?url=stripe.com" |
jq '{id: .core.id, nameBrand: .core.nameBrand, nameLegal: .core.nameLegal,
logoSquare: .core.image.logoSquare,
tag: [.classification.tag[] | {name, isPrimary}],
link: [.urlLink[] | {url, urlType}]}'
{"id": "4eabfc26-3ed9-4ad3-a935-9be07ae3329a", "nameBrand": "Stripe", "nameLegal": "Stripe, Inc.", "logoSquare": "/logos/gfc/gfcNIiXzgUdP6tGupXsKe.png", "tag": [{"name": "Platform", "isPrimary": false}, {"name": "SaaS", "isPrimary": true}], "link": [{"url": "https://stripe.com/", "urlType": "website"}, {"url": "https://www.bloomberg.com/profile/company/1453219D:US", "urlType": "bloomberg"}, {"url": "https://facebook.com/stripehq", "urlType": "facebook"}, {"url": "https://github.com/stripe", "urlType": "github"}, {"url": "https://www.linkedin.com/company/stripe", "urlType": "linkedin"}, {"url": "https://x.com/stripe", "urlType": "twitter"}, {"url": "https://wellfound.com/company/stripe", "urlType": "wellfound"}, {"url": "https://en.wikipedia.org/wiki/Stripe,_Inc.", "urlType": "wikipedia"}, {"url": "https://ycombinator.com/companies/stripe", "urlType": "ycombinator"}]}
FieldHolds
core.nameBrand, core.nameLegalThe name the company goes by and its registered name
core.image.logoSquareThe square logo’s storage path, not a full URL; isMonogram is true for a letter mark
classification.tagTags; isPrimary marks the main one. industry and mainProduct sit beside it
urlLinkCurrent website and profile links, websites first, each with url and urlType
publicUrlThe company’s page on aventure.vc

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:

curl -H "Authorization: Bearer $AUTH_TOKEN" \
"https://api.aventure.vc/v1/entities/4eabfc26-3ed9-4ad3-a935-9be07ae3329a/logo"
{"path": "/logos/gfc/gfcNIiXzgUdP6tGupXsKe.png", "cdnUrl": "https://images-v2.aventure.vc/logos/gfc/gfcNIiXzgUdP6tGupXsKe.png"}

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.

curl -X POST -H "Authorization: Bearer $AUTH_TOKEN" -H "Content-Type: application/json" \
-d '{"url": ["stripe.com", "notion.so", "zzqx-unknown-domain-4417.com"]}' \
"https://api.aventure.vc/v1/entities/lookup-matches"
[{"input": "stripe.com", "inputType": "URL", "status": "MATCHED", "detail": {"core": {"nameBrand": "Stripe"}}}, {"input": "notion.so", "inputType": "URL", "status": "MATCHED", "detail": {"core": {"nameBrand": "Notion", "slug": "notion"}}}, {"input": "zzqx-unknown-domain-4417.com", "inputType": "URL", "status": "MISSING", "candidateEntityId": []}]

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.

curl -X POST -H "Authorization: Bearer $AUTH_TOKEN" \
-H "Content-Type: application/json" \
-d '{"typeRecord":["Company"],"stage":["Seed"],"tag":["Fintech"],"headquartersState":["New York"]}' \
"https://api.aventure.vc/v1/entities/search?size=3"

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.

curl -H "Authorization: Bearer $AUTH_TOKEN" \
"https://api.aventure.vc/v1/entities/4eabfc26-3ed9-4ad3-a935-9be07ae3329a/fundraise-rounds?size=5&sort=dateAnnounced,desc"
curl -H "Authorization: Bearer $AUTH_TOKEN" \
"https://api.aventure.vc/v1/entities/4eabfc26-3ed9-4ad3-a935-9be07ae3329a/fundraise-investor-joins?transactionId=1d9e0ca8-6653-40ee-93ac-6c000e08fe98&size=5"

One recorded Series I round in the example snapshot:

{"id": "1d9e0ca8-6653-40ee-93ac-6c000e08fe98", "round": "Series I", "amountRaised": 6500000000, "currency": "USD", "dateAnnounced": "2023-03-15T00:00:00.000Z", "investorCount": 10}

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.

curl -H "Authorization: Bearer $AUTH_TOKEN" \
"https://api.aventure.vc/v1/entities/lookup-exact?url=sequoiacap.com&typeRecord=Investment%20Firm"
curl -H "Authorization: Bearer $AUTH_TOKEN" \
"https://api.aventure.vc/v1/entities/9187060c-8107-4f4c-9719-f185d2c8ee7d/investments?latestPerEntity=true&dateFrom=2025-01-01&size=3"

Read totalElements for the current portfolio count matching the date filter. One example row, abridged:

{"round": "Series B", "amountRaised": 50000000, "currency": "USD", "dateAnnounced": "2026-09-30T00:00:00.000Z", "entity": {"core": {"nameBrand": "Flow Engineering", "slug": "flow-engineering-san-francisco-ca-us"}}, "investorAttribution": {"leadInvestor": false, "attributionType": "direct"}}

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.

curl -H "Authorization: Bearer $AUTH_TOKEN" \
"https://api.aventure.vc/v1/people/lookup-exact?url=linkedin.com/in/patrickcollison"
curl -H "Authorization: Bearer $AUTH_TOKEN" \
"https://api.aventure.vc/v1/people/44a15937-50df-4970-a32e-130e2c3ca150/entities?size=5"

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.

[{"entityName": "Stripe", "entitySlug": "stripe-south-san-francisco-ca-us", "titleName": "Co-Founder & CEO", "isCurrent": true}, {"entityName": "Auctomatic", "entitySlug": "auctomatic-san-francisco-ca-us", "titleName": "Cofounder", "isCurrent": false, "startDate": "2007-01-01T00:00Z", "endDate": "2008-01-01T00:00Z"}]

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

curl -H "Authorization: Bearer $AUTH_TOKEN" \
"https://api.aventure.vc/v1/entities/4eabfc26-3ed9-4ad3-a935-9be07ae3329a/similar?relationshipType=competitor&size=5"

Each row pairs a company with why it is listed:

{"entity": {"core": {"nameBrand": "Block", "slug": "block-san-francisco-ca-us"}}, "similarity": {"origin": "curated", "curatedRelationshipType": "competitor", "curatedSource": "Stripe competes with Block across payments and financial infrastructure."}}

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.

aventure entities acquisitions list --entity-id 4eabfc26-3ed9-4ad3-a935-9be07ae3329a --role acquirer --size 3

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.

curl -H "Authorization: Bearer $AUTH_TOKEN" \
"https://api.aventure.vc/v1/news?owner.entityId=4eabfc26-3ed9-4ad3-a935-9be07ae3329a&publishedAfter=2026-09-01&size=3"

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

CallCounts against
Full record by URL, slug, or id, and each matched or batch recordOne company or person profile view per distinct record each month; a repeat read that month is free
Company list, logo, rounds, investors, portfolio, roles, and newsNo profile view
Competitors and similar companiesFree on every plan

Plans and usage covers every allowance, and the API reference lists every parameter and response field.