GatherHQ

Tools API

Quotes, stats, content, studies, personas, exports, answers from your research, study design and simulations from your own GatherHQ workspace, in Clay, HubSpot or any app that can make an HTTP request.

Every tool works with your workspace as the person behind your key, with the same inputs and rules as the GatherHQ MCP. Launching a study to real people and running a simulation need GatherHQ credits or a contract.

Request

POST https://synthetic.gatherhq.com/api/v1/tools/gather_find_quotes
Authorization: Bearer <your GatherHQ API key>
Content-Type: application/json

{"search": "pricing objections", "limit": 5}

Put the tool's name in the path and its input in the body, as JSON: {}, or no body, for a tool that takes none. Use an API key made in GatherHQ (workspace admins make them under Settings > API keys) or an agent key, in the Authorization header or as x-api-key, never on the URL. A key acts as the admin who made it.

Tools

gather_research_answer · Write

Answers a question about your customers from your completed studies and the files you added to GatherHQ, with counted numbers and word-for-word quotes. Your question and the start of the answer are saved to your workspace.

Inputs: question; study_id (optional)

gather_find_quotes · Read only

Searches or browses your verbatim library: quotes from real respondents in your completed studies.

Inputs: search, study_id, limit (1 to 15), all optional

gather_find_stats · Read only

Finds stats for an email, an ad or a slide: the stat and headline of your finished social cards that fit, each with its source line and a link to the card.

Inputs: industry, role, topic, limit (1 to 25), since (YYYY-MM-DD), all optional

gather_list_studies · Read only

Lists your 20 newest studies with their status and ids; a search or status narrows those 20.

Inputs: search, status (draft, live, in review, completed), both optional

gather_list_personas · Read only

Lists your buyer personas and the key to ask each one.

Inputs: none

gather_list_content · Read only

Links your core research assets and the content made from your studies.

Inputs: scope (all, core, library), optional

gather_get_test_link · Read only

Returns a link to try a study's interview before it launches.

Inputs: study_id

gather_ask_persona · Write

Asks one of your buyer personas a question. Answers are simulated; a question its research does not cover is logged to the persona's research backlog.

Inputs: persona_key, question

gather_research_ideas · Write

Suggests research ideas with current signals from the web, and saves them to your workspace.

Inputs: none

gather_create_content · Write

Creates a report, blog post, ebook, slide deck or social card from a completed study.

Inputs: study_id, kind; brief (optional)

gather_design_study · Write

Designs a study with real people one question at a time in a new draft study, shares a research plan and interview guide for your approval, then builds the interview and tries to set up its audience, or says GatherHQ's research team is finishing the targeting.

Inputs: instructions; study_id to continue a design; approve (true once you approve the plan)

gather_set_study_audience · Write

Sets who a draft study recruits, with screener questions, or says GatherHQ's research team is finishing the targeting. A live study's audience cannot change from here.

Inputs: study_id, instructions

gather_export_responses · Write

Exports a study's conversations as a CSV behind a private link that works for 60 minutes.

Inputs: study_id; include_incomplete, start_date, end_date (optional)

gather_run_simulation · Write

Starts a simulation of how your saved personas would react to a change or idea, and waits up to about 3 minutes for the results. Needs GatherHQ credits or a contract.

Inputs: topic (12 to 1,800 characters), audience (b2b or b2c)

gather_get_simulation · Read only

Returns the status or results of a simulation you started, waiting up to about 3 minutes while it runs.

Inputs: simulation_id

gather_launch_study · Write, cannot be undone

Launches a built study to real people. Needs GatherHQ credits or a contract, and your explicit go-ahead.

Inputs: study_id

Response

{
  "object": "tool_result",
  "tool": "gather_find_quotes",
  "data": {
    "mode": "search",
    "search": "pricing objections",
    "returned": 1,
    "quotes": [
      {
        "quote": "<a respondent's words, exactly as they said them>",
        "question": "<the question they answered>",
        "themes": ["<theme>"],
        "sentiment": "<sentiment>",
        "from_study": "<the study's name>",
        "date": "<YYYY-MM-DD>"
      }
    ],
    "studies": [{ "study_id": 1201, "name": "<the study's name>", "quotes": 24 }]
  },
  "text": null
}
  • data is the tool's answer when it is JSON: quotes, stats, studies, personas, content, test links, exports and simulations.
  • text is its answer in words when it is not: an answer from your research, a launch, or a study GatherHQ's research team is finishing. Share it as written.
  • The other is null.

Use it in Clay

  1. In your table, click Add enrichment, search for HTTP API, and open the Configure tab.
  2. Method POST, Endpoint URL https://synthetic.gatherhq.com/api/v1/tools/gather_find_quotes, or any tool's name in its place.
  3. In the JSON body, put the tool's input, with a column as /Column Name in quotes: {"search": "/Job Title", "limit": 3}.
  4. Under Select header account, click + Add account and add Authorization with Bearer <your GatherHQ API key> under API Request Headers, then Save it, so the key is not shown in the column.
  5. Field paths to return: data.quotes, or text for a tool that answers in words.
  6. Set rate limiting to 5 requests per 1000 ms, click Test on one row, then run the column.

Errors and limits

400 invalid_requestAn input to fix; the message names it.
401A missing, bad or revoked key.
403The person behind the key can no longer open the workspace.
404 not_foundNo tool of that name; the message lists them.
413, 415A body over 100,000 bytes, or one not sent as Content-Type: application/json.
422 refusedThe tool will not do it, for example a launch without GatherHQ credits; the message says why.
429 rate_limitedThe key's 2,000 workspace requests for the day are used. They reset at 00:00 UTC.
502 upstream_errorGatherHQ could not do it, or its answer did not arrive. retryable says whether to send it again.
503Retry shortly.
504 timeoutNo answer in time. A tool that changes something may still have done it: the message says how to check first.

Each key made in GatherHQ can make 2,000 workspace requests a day, on this API and the MCP together. They do not count against the key's report runs. For stats alone, the Stats API takes a GET and has its own daily count.