Docs

Research

Search starts research: search.query with route "research" (MCP search_customers) hands Amdahl one question and returns one cited answer from a read-only job that investigates it over your calls, CRM accounts and deals. Poll research.get for the answer.

Research takes one question about your customers and returns one answer, with the evidence it rests on. A read-only agent works the question server-side: it queries your call transcripts, CRM accounts and deals, reads the themes your customers raise, counts distinct companies behind each claim, and writes the answer with each claim cited to a table, a quote or a theme it actually read.

Search starts research. Send the question to search.query (MCP search_customers) with route: "research", and read the job with research.get (MCP get_research) or with search.query and only research_id. On a workspace with search_research_routing turned on, route: "auto" also hands a statistical ask to a research job. See Routing a statistical ask to research.

Reach for it when a question needs several reads and a written synthesis ("why are mid-market deals stalling this quarter?"). For one fast lookup, use Search. Research reads only your own workspace data. It does not search the web, and it does not write a multi-step deliverable such as a brief saved to the workspace.

OperationRESTMCPScope
Start a jobsearch.query with route: "research"POST /search/querysearch_customers with route: "research"data:read and conversations:write
Read a jobresearch.getGET /research/:idget_researchconversations:read
Answer its questionresearch.respondPOST /research/:research_id/respondanswer_research_questionconversations:write
Stop a jobresearch.cancelPOST /research/:research_id/cancelcancel_researchconversations:write
Start a job (deprecated)research.startPOST /researchstart_researchconversations:write

A Customer agent key carries every scope above. A Read only key can read a job but cannot start one: its route: "research" search gets a search answer and a note that says why.

POST/search/queryauth required

With route: research, start a research job. Returns a research_id at once.

POST/researchauth required

Deprecated. Start a research job directly. Returns a research_id at once.

GET/research/:idauth required

Read a job: its status, the question it is waiting on, and once complete the cited answer. Pass wait_ms to wait for it to settle.

research.start is deprecated

research.start (POST /research, the MCP tool start_research) is deprecated. It stays available — removal will not happen before 2026-11-23, and will be announced here first. The same job is also reachable from Search: search.query with route: "research" (or the MCP search_customers tool) starts it, and research_id polls it — one call for both halves. It takes the same 10,000-character query and 4,000-character context, and route: "research" works on every workspace. research.get / get_research is not deprecated and is unaffected either way.

What a job can do

A research job reads this workspace's own data: the interactions warehouse, deals and deal qualification, the conversation themes, and saved documents. It writes nothing, sends nothing, and fetches nothing from outside your workspace: no web or market search, and no lookup of a social profile. The role the job runs under enforces that, not its instructions, so a question cannot talk it into a write or an outside fetch.

It also reaches two things a single search call cannot: the deal's stage history (so "did this call move the stage" or "where were they in the funnel when X happened" gets the stage at that moment, not just the deal's current stage), and, where this workspace has it, a matched-control win-rate lift per positioning claim or phrase (with a confidence tier and an honest flag for a confounded or thin sample). Ask "which phrases or claims predict a deal moving forward" and the job reaches for this instead of a plain word count.

A job takes a deal's state from the data, not from the question. When a question calls deals "stalled", "fast movers", "lost" or "at risk", the job checks each deal it names against its stage, its last stage change and its last conversation. Where the data disagrees with the question's label, the answer says so in its first lines and gives the dates.

Start a job

Send POST /search/query with route: "research". The whole query becomes the job's question, and context its background:

json
{
  "query": "Why are mid-market deals stalling this quarter?",
  "context": "For the Q4 board deck. We changed pricing in August.",
  "route": "research"
}

The response comes back at once, with mode_ran: "research", empty results, and research: { research_id, chat_id, status, poll }. Routing a statistical ask to research shows the full body and what happens when the start is refused. A job started from search never pauses to ask a clarifying question (allow_questions: false). It takes its date cut from the session's X-Amdahl-As-Of header or from a date the question names (Pin a job to a date).

The deprecated research.start (POST /research) starts the same job and takes the fields below:

json
{
  "question": "Why are mid-market deals stalling this quarter?",
  "context": "For the Q4 board deck. We changed pricing in August.",
  "allow_questions": true
}
  • question (required): the question, in plain language, up to 10,000 characters.
  • context (optional, up to 4,000 characters): what the job should know. Who the answer is for, what you already know, the decision it feeds. It is read as background, never as the question.
  • allow_questions (optional, true when omitted): lets the job pause to ask you a clarifying question when the question is ambiguous in a way that changes the answer. Send false when nobody will answer; the job then proceeds on its best reading and states the assumption in its answer.
  • as_of (optional): an ISO-8601 date or timestamp, such as "2026-10-23". A bare date means the end of that day, UTC, the same as a date in the question; send a timestamp such as "2026-10-23T08:00:00Z" for another instant. null or "live" ignores a date the question names and reads current data; it does not lift a session's X-Amdahl-As-Of cut. The job's data.query, theme (cluster) and search.query reads see the workspace as it stood then. Calls and emails after it are hidden, and each deal carries the stage it was in at that instant, so a deal lost the next day still reads as open. Saved-document search (data.search), context.query_substrate and resource reads do not apply the cut yet, so a document written after it can appear. See Pin a job to a date.

Any other field is refused with 400 invalid_argument, naming it. The response comes back at once:

json
{
  "data": {
    "success": true,
    "research_id": "8b0f2c4e-1d7a-4f0e-9a51-2f3c8d6e7b10",
    "chat_id": "f3a9e1d2-5b6c-4a7d-8e9f-0a1b2c3d4e5f",
    "status": "queued",
    "as_of": null
  }
}

chat_id is the id of the conversation the job runs in. Quote it in a support request. No route reads a conversation by this id: read a job with research_id.

A question that was already answered

When your workspace already has a finished answer to the same question, the start returns that job instead of a new one. The response then carries "status": "complete" and "cache_hit": true, and research_id names the finished job: read it with research.get as usual. A start answered this way does not count toward the monthly cap.

Every such response also carries cached_answer, so you can show the answer's date:

FieldMeaning
matchexact for the same question. structured for a question with the same meaning (see below).
data_as_ofThe instant the answer's data describes: the job's cut, or when the job started.
age_secondsHow long ago the answer was stored.
questionWith structured only: the question the cached answer was written for.
json
{
  "data": {
    "success": true,
    "research_id": "8b0f2c4e-1d7a-4f0e-9a51-2f3c8d6e7b10",
    "chat_id": "f3a9e1d2-5b6c-4a7d-8e9f-0a1b2c3d4e5f",
    "status": "complete",
    "as_of": null,
    "cache_hit": true,
    "cached_answer": {
      "match": "exact",
      "data_as_of": "2026-10-27T10:00:00.000Z",
      "age_seconds": 5400
    }
  }
}

A start reuses a job only when all of these hold:

  • The question and context match. Extra spaces and a trailing ?, . or ! are ignored; letter case is not.
  • The job reads under the same cut (as_of). A job over current data is reused only on the same UTC day, because a window such as "last 60 days" ends on the day the job ran.
  • allow_questions matches, and the caller sees the same data (the same data access rules in the workspace).
  • The job finished with a full answer. A partial answer, a failed or canceled job, and a job that asked you a clarifying question are never reused.
  • No call, email or deal arrived in the workspace, and no call or deal record changed, since the job started. For a job with a cut, only calls and emails dated at or before the cut, and deals created at or before it, count: data that arrives later, dated after the cut, does not end the cached answer.
  • The job finished less than one day ago.

Ask a different question, or change context, to start a new job.

A question with the same meaning (beta)

On a workspace where Amdahl has turned it on, a start can also return a finished job for a question worded differently but asking the same thing: the same kind of question, the same group of buyers, the same named accounts, the same outcome (won, lost, both or open deals), the same time window and the same cut. Such a response has "match": "structured" and carries the cached job's own question, so you can check that it answers yours. A job is reused this way only when no call has landed on, and no deal has changed stage on, any account it read since it started. An answer under a cut is reused for up to 7 days; an answer over current data until the end of its week, or of its day when the question names a time window. Lead names that match no account in the workspace are left out of the match. A question that names a time the matcher cannot read exactly (a year, a quarter, "since the pricing change") is never matched this way. The check watches only the accounts the cached job read: a new account or deal in the segment that the job never read does not end the answer before its lifetime is up.

On the same workspaces, a start that begins a new job can also carry related_research: up to three finished jobs for questions close to yours, each with its research_id, its own question, its data_as_of and a similarity from 0 to 1. They are suggestions, never the answer: the new job runs and counts as usual. When one of them already answers your question, read it with research.get and stop the new job with research.cancel. Only jobs that read the same data you can see, in the same kind of question, outcome, window and cut, are suggested.

On a workspace with no connected source the job has nothing to read. If the workspace also holds no conversation themes, the start is refused with 409 and error.code: "setup_needed" before a quota call is counted, and no job starts. Otherwise the start still succeeds. Either way the response carries setup_needed with a message and a connect_url for the user. Show them both, and do not retry until a source is connected. See A workspace with nothing connected, the setup_needed handling in Errors, and the FAQ.

Research for a campaign

A campaign usually needs one answer per segment, not one per lead. Ask it that way:

  1. Group the campaign's leads by segment (for example "GTM and outbound agencies", "AI SDR startups", "founder-led sales teams").
  2. Start one job per segment. Name the segment and leave out lead names: a name that matches no account in this workspace makes the job spend turns proving that, and adds no findings.
  3. Set as_of to the moment you assemble the campaign, as a full ISO-8601 instant, and send the same value for every segment. Every job then reads the same data, and the answers say which instant they describe. Do not send a bare date for today or a later day: it means the end of that day, so jobs started at different times read different data, and each call that lands during the day ends the cached answer.
  4. Keep each research_id with the campaign. Read it again with research.get (MCP get_research) for every message in that segment, instead of starting a new job.
json
{
  "question": "What do GTM and outbound agencies say about reply rates, and what made them buy or not?",
  "as_of": "2026-10-27T15:04:05Z"
}

A second start of the same question with the same as_of may return the finished job, which does not count toward the cap (A question that was already answered). A finished job is reused only within a day, and only while no call or deal at or before the cut has changed, so holding the research_id is the surer way to reuse it, because a reworded question starts a new job.

Campaign briefs (beta)

On a workspace where Amdahl has turned it on, POST /research/briefs (research.start_brief) does the steps above in one call. Send the campaign's segments, each with one question, and optionally the campaign date as as_of (it defaults to the moment the brief is created), a shared context, and refresh:

json
{
  "segments": [
    { "segment": "GTM and outbound agencies", "question": "What do GTM and outbound agencies say about reply rates, and what made them buy or not?" },
    { "segment": "AI SDR startups", "question": "What do AI SDR startups say about reply rates, and what made them buy or not?" }
  ],
  "as_of": "2026-10-27",
  "refresh": true
}

The request stores the brief and answers 202 with a brief_id and each segment's state (starting), without waiting for the jobs. The jobs start in the background, three at a time. Each distinct question becomes one research job, started exactly as research.start would start it for you, with allow_questions: false: it counts toward the monthly cap, and a question already answered comes back as that finished job, free. Two segments with the same question share one job. If the cap is already reached, the request is refused with 429 and stores nothing. A segment whose start the cap refuses later shows state: "error".

GET /research/briefs/{brief_id} (research.get_brief, resource research_brief://<id>) lists the segments with each research_id as it appears, its state (starting, started, error, or interrupted when a start never finished) and the job's current status. Read each answer with research.get.

A retry is safe. Send an idempotency_key, or send as_of and an identical body: a repeat returns the first brief (replayed: true) and starts no second set of jobs, even when the monthly cap has been reached since. The key belongs to you: another member's brief is never returned for it. A repeat that reuses your key with a different body is refused with 409 conflict (reason: idempotency_key_reused). If a start was interrupted (for example by a deploy), Amdahl starts it again, once: a retry takes it over, and so does the nightly check. Each segment is started by one runner at a time, so a retry never bills the same segment twice. A brief whose distinct questions do not fit in what is left of the monthly cap is refused with 429 before anything is stored. A session X-Amdahl-As-Of cut clamps the brief the way it clamps research.start, each segment records the cut its job actually ran under, and a brief under a session cut cannot use refresh.

With refresh: true, Amdahl checks the brief every night for 7 days. When a call lands on, or a deal changes stage on, an account a segment's answer read, that segment is asked again at that night's date. The new job starts as you: your workspace role and scope are checked again first, so a brief stops refreshing if you are removed or lose the right to start research (the check does not look at whether the API key or OAuth grant that created the brief still exists), and each refresh counts toward the monthly cap like a start you made yourself. The brief then names the new job and keeps the old one in previous_research_ids. A segment whose answer cannot be checked is left as it is.

Over MCP, start one job per segment as described above. Only the deprecated start_research takes the as_of instant that step 3 asks for. search_customers with route: "research" takes its cut from the session's X-Amdahl-As-Of header or from a date the question names, and a date in the question means the end of that day.

Pin a job to a date

A job reads current data unless it has a cut. The cut comes from the first of these that is present:

  1. The as_of field. When the request also carries X-Amdahl-As-Of, the field wins only if it is at or before the header's value, and the echo shows the header's value as session_at.
  2. The X-Amdahl-As-Of header on the request, the same header that pins a backtest session. A bare date in the header means 00:00 UTC that day, as it does on every other read in the session, so a job never reads later than data.query does under the same header. A bare as_of date on the header's own day means the end of that day, which is later, so it is clamped to the header's 00:00.
  3. A date the question names: "as of Oct 23 2026", "on or before Oct 23 2026", "through Oct 23 2026", or the end of a range such as "Aug 24 to Oct 23 2026". The cut is the end of that day, UTC. The end date needs a year. No cut is taken from a question that names two different end dates, from a date in the future, or from a question that also asks about what came after the date ("later", "afterward", "after that", "went on to", "ended up", "then", "outcome", "versus", "compare"). A range's end is also not taken when the question asks about the present ("since", "still", "now", "today", "currently"). Send as_of: "live" to read current data whatever the question says.

The X-Amdahl-As-Of header is a ceiling for a research job. An as_of later than the header's value is clamped to it: the job runs at the header's value, and the echo shows source: "session" with your value as clamped_from. The same rule holds for the as_of parameter on data.query, data.cluster_search and data.cluster_detail in a session opened with the header: a later value reads at the header's instant, and the response carries as_of_clamped: { requested, applied }. An as_of or header value that does not parse is refused with 400 invalid_argument, before a quota call is counted. The cut the job runs under is echoed as as_of on the start response and on every read: null, or { "at": "2026-10-23T23:59:59.999Z", "source": "question", "phrase": "Aug 24 to Oct 23 2026" }, where source is as_of, session or question, phrase appears only for question, session_at appears when the request also carried X-Amdahl-As-Of and the field was at or before it, and clamped_from appears when the field was later and was clamped.

Under a cut a deal is read from its stage history, so the job can name the deal's company but not the deal's own name. A relative window in the question ("last 60 days") ends at the cut.

Read a job

GET /research/:id?wait_ms=45000 holds the connection for up to 45 seconds until the job settles, then returns the same body an immediate read would. Call it again while status is running. Over MCP, get_research waits up to 25 seconds when no wait_ms is sent; send wait_ms: 0 to read at once. If the server is already holding as many reads as it can, the body carries a wait_note and returns at once. A typical job settles in one to a few minutes.

json
{
  "data": {
    "research_id": "8b0f2c4e-1d7a-4f0e-9a51-2f3c8d6e7b10",
    "chat_id": "f3a9e1d2-5b6c-4a7d-8e9f-0a1b2c3d4e5f",
    "status": "complete",
    "question": "Why are mid-market deals stalling this quarter?\n\nContext from the caller: For the Q4 board deck. We changed pricing in August.",
    "question_for_you": null,
    "answer": {
      "text": "Security review is where mid-market deals stall: 6 of the 11 stalled deals this quarter are waiting on it...",
      "partial": false,
      "partial_reason": null,
      "content_blocks": [],
      "follow_ups": ["Which security questions come up most often?"]
    },
    "answered_questions": [],
    "error": null,
    "created_at": "2026-10-02T15:04:11.000Z",
    "started_at": "2026-10-02T15:04:12.000Z",
    "completed_at": "2026-10-02T15:06:40.000Z"
  }
}
statusWhat it meansWhat to do
runningThe job is working, or queued to start.Read again with wait_ms.
needs_inputThe job paused on a clarifying question, in question_for_you.Answer it with research.respond.
completeanswer holds the result.Read answer.
failedThe job could not answer. error says so in one sentence; error_reason names why.See A failed job.
canceledThe job was stopped.Nothing.

answer is null until the job is complete, so a draft is never read as the result. A read of an id that is malformed, missing, in another workspace, or a run that is not a research job returns 404.

A failed job

error_reason is one of timeout, model_error, model_output_limit, tool_error, cost_cap, or unknown — enough to decide whether retrying as-is is worth it (a timeout or model_error might clear on its own) or whether to ask a narrower question (cost_cap: the job used its full budget before it could write an answer; model_output_limit: the answer needed a longer reply than a research job allows in one step). error stays one fixed sentence per reason; it never carries the job's own internal error text.

json
{
  "data": {
    "research_id": "8b0f2c4e-1d7a-4f0e-9a51-2f3c8d6e7b10",
    "status": "failed",
    "error": "The research job used its full budget before it could write an answer. Start it again with a narrower question — see partial_findings for what it had before it ran out.",
    "error_reason": "cost_cap",
    "answer": null,
    "partial_findings": [
      { "id": "blk_1", "type": "table", "title": "Mid-market deals by stall reason" }
    ]
  }
}

partial_findings carries any evidence the job had already presented (a table, a quote, a theme finding) before it failed, so a job that ran out of budget mid-investigation does not come back completely empty. It is null when the job failed with nothing presented yet.

The answer

  • text is the answer as markdown. It is never empty on a complete job that found anything: when the job wrote no closing prose, text lists each of the content_blocks findings by label, with its insight or value.
  • content_blocks is the evidence the answer presents: tables carrying the query that produced them, verbatim customer quotes with their source, and theme findings.
  • follow_ups lists questions the job suggests asking next.

Partial answers

Every job has a fixed budget of model usage and steps. A job that reaches it does not stop empty-handed: it writes its best answer from what it already found, says which parts of the question it did not get to, and completes with partial: true. partial_reason is usage_limit or turn_limit. Report a partial answer as partial. If that last step produces no answer at all, the job ends failed rather than passing off an earlier draft.

Clarifying questions

When status is needs_input, question_for_you holds the question:

json
{
  "kind": "multiple_choice",
  "question": "Which product line should I focus on?",
  "options": [
    { "id": "opt_1", "label": "Core platform" },
    { "id": "opt_2", "label": "Analytics add-on" },
    { "id": "other", "label": "Other" }
  ]
}

Answer it with POST /research/:research_id/respond:

json
{ "answer": "Analytics add-on" }

Send your answer as text: on a multiple-choice question, the label of a choice selects it, and any other text is sent as the Other write-in. Pass option_id to pick a choice by id; the answer text then travels only with other, and a free-form question ignores option_id. The job resumes and reads as running again. Answering a job that is not waiting on a question returns 409 conflict.

Stop a job

POST /research/:research_id/cancel stops a job that is running or waiting on its question. A job that already ended returns 409 conflict and is left as it is.

Over MCP

Each call is its own tool. search_customers with route: "research" starts a job. answer_research_question and cancel_research change jobs, so a client may ask the user to approve those calls. cancel_research is marked destructive because it stops a job in progress. get_research only reads and changes nothing. The deprecated start_research starts the same job, until its removal no earlier than 2026-11-23.

code
search_customers { query: "Why are mid-market deals stalling this quarter?", route: "research" }
get_research { research_id: "<research_id>", wait_ms: 45000 }

A job that start_research started can wait on a question, unless the start sent allow_questions: false. Answer it with answer_research_question { research_id: "<research_id>", answer: "Analytics add-on" }.

A job is also readable as the resource research://<id>.

Monthly cap

Each job started with an API key or an external OAuth token, MCP included, counts toward a monthly cap of 100 per workspace. A start is counted the moment it is accepted, before the job runs, so a start that later fails still counts. Past the cap, research.start returns 429 quota_exceeded with the limit and usage in details, and no job starts; simultaneous requests can pass it by at most a start or two. The cap resets at the start of the next month; ask Amdahl support to raise it. Jobs started from the Amdahl console do not count. A start refused with 409 setup_needed does not count either, and neither does a start answered by a job that already finished (A question that was already answered). See Do failed or refused calls count toward my quota?