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
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
}datais the tool's answer when it is JSON: quotes, stats, studies, personas, content, test links, exports and simulations.textis 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
- In your table, click Add enrichment, search for HTTP API, and open the Configure tab.
- Method POST, Endpoint URL
https://synthetic.gatherhq.com/api/v1/tools/gather_find_quotes, or any tool's name in its place. - In the JSON body, put the tool's input, with a column as
/Column Namein quotes:{"search": "/Job Title", "limit": 3}. - Under Select header account, click + Add account and add
AuthorizationwithBearer <your GatherHQ API key>under API Request Headers, then Save it, so the key is not shown in the column. - Field paths to return:
data.quotes, ortextfor a tool that answers in words. - Set rate limiting to 5 requests per 1000 ms, click Test on one row, then run the column.
Errors and limits
400 invalid_request | An input to fix; the message names it. |
401 | A missing, bad or revoked key. |
403 | The person behind the key can no longer open the workspace. |
404 not_found | No tool of that name; the message lists them. |
413, 415 | A body over 100,000 bytes, or one not sent as Content-Type: application/json. |
422 refused | The tool will not do it, for example a launch without GatherHQ credits; the message says why. |
429 rate_limited | The key's 2,000 workspace requests for the day are used. They reset at 00:00 UTC. |
502 upstream_error | GatherHQ could not do it, or its answer did not arrive. retryable says whether to send it again. |
503 | Retry shortly. |
504 timeout | No 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.