cancel-chat-turn
ChatGPTStops a running Happenstance Chat turn, like the Stop button in the app. Without turnId it stops whatever the chat is working on. Chat keeps what it already wrote and its searches stop. The turn reads cancelled within a few seconds and is charged for the work done. A turn that already finished is returned as it is.
chat
ChatGPTUse this when the user wants to find people or reach them through their network: warm intros, who they know at a company, hiring, fundraising, sales or questions about a person, even when they say "search". Do not use search-network or research-person for these unless the user explicitly asks for a Happenstance search or research instead of Chat. Sends a message to Happenstance Chat, an agent that works on the user's professional network: it runs searches across the user's connections, their friends' connections and their groups, checks people on the web, explains why each person fits and who can introduce them, and drafts outreach. Omit chatId to start a new chat; pass the chatId of an earlier chat to continue it, since Chat keeps what the user said before (goals, exclusions, style). Start a new chat for a new goal: long chats cost more per turn. Returns at once with a chatId and turnId: call get-chat-turn until the turn is completed, which usually takes 1 to 3 minutes when Chat searches. A message sent while Chat is still working joins that turn (joined: true): keep polling the same turnId, and its reply and charge cover both messages. When a turn ends with stop_reason needs_input, Chat asked questions with options (reply.questions in get-chat-turn) and waits: answer the ones you can from what you know of the user and this conversation, ask the user the others, then call chat with the chatId and answers (or a message that answers in words). Chat's replies need no acknowledgement. Happenstance never sends, posts or connects on the user's behalf: its drafts are for the user, and you may send them with your own tools only if the user asks. A chat started here has no scheduled tasks: when the user wants recurring results (for example, new matches every Monday), send the chat a message on that schedule yourself, such as "any new matches since last time?"; Chat keeps the conversation, so it can leave out people it already showed. Each turn is charged when it finishes. Chat turns have variable cost depending on how much work is done, often 1–4 credits.
create-credits-checkout-session
ChatGPTCreates a Stripe checkout session to purchase Happenstance credits. Returns a checkout URL that the user can open in their browser to complete the purchase. Available packages: 100 credits ($25 - $0.25/credit), 1000 credits ($200 - $0.20/credit), 10000 credits ($1500 - $0.15/credit). After purchase, credits are automatically added to the user's account via webhook — no manual step needed. Use get-credits first to check the user's current balance before suggesting a purchase. You can also check to see if the user has auto-reload enabled. If the user is unsure how many credits to buy, recommend 100 credits to start. IMPORTANT: Always return the full checkout URL to the user exactly as provided — do not truncate or shorten it. Documentation: https://developer.happenstance.ai
find-more-results
ChatGPTFind more results for an existing Happenstance search. Use this instead of starting a new search when you want additional results — it guarantees different people by excluding everyone already returned. Only call this when has_more was true in a previous get-search-results response. Costs 2 credits. Returns a page ID to use with get-search-results. After calling this, use get-search-results with the original searchId plus the returned pageId to poll for and retrieve the new results. Documentation: https://developer.happenstance.ai
get-chat
ChatGPTReturns a whole Happenstance chat: every message (Chat's replies as markdown), its turns and their status (in a chat started in the app, including runs of its scheduled tasks), the searches it ran, the scheduled tasks of a chat started in the app (instruction, cron schedule, next run, paused), and the notes Chat keeps on the user's goal, preferences and exclusions. Use it to pick up a chat the user started in the Happenstance app or earlier. Chats started in the app can be read but not continued here. Free.
get-chat-drafts
ChatGPTReturns the message drafts Happenstance Chat wrote in a chat: recipient, person ID when known, kind (outreach, intro request, forwardable blurb, template, post or email), the text, and the turn that wrote it. By default only the latest version for each recipient: a draft Chat revised in a later reply replaces the earlier one, and drafts written together (two intro requests to the same friend) are all returned. Happenstance never sends them; send them with your own email, LinkedIn or other tools only if the user asks. Free.
get-chat-people
ChatGPTReturns the people Happenstance Chat showed in a chat, one row per person with their latest card: name, title, company, location, LinkedIn URL, whether the user knows them directly and through which sources, the mutuals who can introduce them with connection strength, the section Chat put them in, and Chat's reasoning with its links. Covers the whole chat in order of first appearance, or one turn with turnId. 100 people per page. Use it to build tables, spreadsheets, CSV files or CRM records. Free.
get-chat-turn
ChatGPTReturns a Happenstance Chat turn: what started it (started_by: message, or schedule for a run of a scheduled task in a chat started in the app, whose message is the task's instruction), its status (queued, running, completed, failed or cancelled), Chat's reply so far as markdown (reply.markdown is the answer to relay; reply.updates holds Chat's earlier progress notes, which may be out of date), the number of people and drafts it produced, the searches it ran (readable with get-search-results), and the credits charged once it finishes. Without turnId it returns the chat's latest turn: the one Chat is working on, or the last one it finished. Call it every 5 seconds for the first minute, then every 10 seconds, until the status is no longer queued or running; while it runs it returns only progress (elapsed time, searches, the start of the reply), and the full turn once it ends. Not rate limited.
get-credits
ChatGPTGets the user's credit balance, purchase history, usage history, and auto-reload settings. Call this proactively before running searches or research to make sure the user has enough credits. Also call this after completing searches or research so the user can see their updated balance. If the balance is low, let the user know and suggest using create-credits-checkout-session to purchase more. Documentation: https://developer.happenstance.ai
get-group
ChatGPTGets details of a specific Happenstance group including its full member list. Returns the group name, image, slug, member count, and each member's name and profile image. Use get-groups first to discover available group IDs, then use this tool to see who is in a specific group. This is especially useful for at-mentions in searches. You can @mention a group member's name in a search query to filter results to that person's connections (e.g. "engineers @Jane Smith knows"). Use this tool to look up the exact name to at-mention. Documentation: https://developer.happenstance.ai
get-groups
ChatGPTGets the Happenstance groups the user is a member of. Returns a list of group IDs and names. Use get-group with a specific group ID to see its members. Knowing group members enables at-mentions in searches — @mentioning a person's name in a search query filters results to that person's connections. Documentation: https://developer.happenstance.ai
get-research-results
ChatGPTGet the status and results of a Happenstance person research. Call this after research-person to check if the profile is ready. If status is "running", wait a bit and call again. If status is "completed", the full profile is included in the response. Documentation: https://developer.happenstance.ai
get-search-results
ChatGPTGet the status and results of a Happenstance network search. Call this after search-network to check if results are ready. If status is "running", wait a bit and call again. If status is "completed", the results are included in the response. IMPORTANT — Understanding the mutuals structure: The response uses a normalized format. There is a top-level "mutuals" array containing all unique mutual connections across all results. Each person in the "results" array has a "mutuals" field with references (by index) into that top-level array, along with an affinity_score. When presenting results, resolve ALL mutual references for each person — not just the first one. Each person may have multiple mutuals who can make an introduction. IMPORTANT: If has_more is true in the response and you want more results, use the find-more-results tool instead of starting a new search. It guarantees different results by excluding all previously returned people. Note: find-more-results costs 2 credits (same as a new search). After calling find-more-results, call this tool again with the original searchId plus the returned pageId to poll for and retrieve the new results. Documentation: https://developer.happenstance.ai
get-user
ChatGPTGets the current user's Happenstance profile information. Returns email, name, profile image URL, and a list of the user's friends (names). Use this to identify who the current user is or to personalize responses with their name. Documentation: https://developer.happenstance.ai
list-chats
ChatGPTReturns the user's Happenstance chats, most recently active first, with title, source (api: started here and can be continued with chat; app: started in the Happenstance app, read only), status, number of turns, and number of scheduled tasks (schedule_count, only in chats started in the app; use it to find the chat a recurring search the user set up in the app runs in). 50 per page. Free.
research-person
ChatGPTResearch a specific person to get detailed professional profile information. This tool starts the research and returns immediately with a research ID. The research runs asynchronously and can take 30+ seconds to complete. Use the get-research-results tool with the returned research ID to check status and retrieve the profile. Costs 1 credit per request. Documentation: https://developer.happenstance.ai
search-network
ChatGPTHappenstance is a People Search Engine that takes natural language queries and returns a list of people that match the query. This tool starts a search across the user's network. It returns immediately with a search ID. The search runs asynchronously and can take a few minutes to complete. Use the get-search-results tool with the returned search ID to check status and retrieve results. If the user asks explicitly for people they know, set includeGroups to false, includeFriends to false, and includeConnections to true. You can use @mentions in the search query to filter results to a specific person's connections (e.g. "engineers @Jane Smith knows"). You can at-mention your friends or other members of a group that you are in. Use get-groups and get-group to look up member names for at-mentions, use get-user to look up your friends for at-mentions. Documentation: https://developer.happenstance.ai