Terac

Approve a submission that is AWAITING_REVIEW. Approving pays the expert and marks the submission as accepted toward the opportunity's target count. Only submissions in AWAITING_REVIEW can be approved, calling on any other state returns a PRECONDITION_FAILED error. Use terac_get_submissions to find submissions awaiting your review. Review the submission's deliverables against the success/failure criteria you wrote in the task description before approving. Approval is how experts get paid, so it commits funds.

Create a DRAFT opportunity directly, with full control over tasks, structured targeting filters, screening questions, and quotas. Nothing is charged and no recruitment starts until you call terac_launch_draft_opportunity. Use this draft-first path when you need precise, structured targeting rather than a free-text panel description. ## Before you call this tool terac_get_context's operating guide sorts every study value into ASK, PROPOSE-and-CONFIRM, and ASSUME. This tool is where that sorting binds: do not call it while an ASK value is still unknown. Do not dump every missing value into one message. A numbered list of four is a form, and a form gets skimmed, which is how the answer that mattered gets a careless number. How many to send at once is your judgement, so decide it like this: ask only what you genuinely cannot proceed without, lead with the one that changes the study most, and add a second only when it is answered in the same breath (count and budget, country and language). Anything whose answer would change what you ask next goes in a later message, alone. One good question is a better opener than three adequate ones. A free draft is not a way around this either, because a guessed participant count or an empty audience reads as a decision once it is in the builder. Creating a project with terac_create_project meanwhile is fine; creating an opportunity is not. Everything in the PROPOSE bucket is yours to fill in with your best value. Do not hand the customer a blank form: choose the method, the task structure, the screener wording and the quotas, then surface them for confirmation at hand-off. ## How many opportunities to create Default to ONE opportunity. Split into separate opportunities only when a segment is a DISTINCT DELIVERABLE, it needs its own sample target, its own language/localization, or independent launch/pause/pricing. In practice that usually means splitting by market when each market has its own quota and localized screener (US, UK, and Germany at 20 interviews each with a localized screener = three). Do NOT split when the segments are one eligible pool that shares a sample, language, and task. Multiple countries recruited as a single pool (e.g. English-speaking experts across US/UK/Canada with one combined sample) go in ONE opportunity via a multi-value country filter; likewise multiple roles, audiences, or seniorities in the same market belong in one opportunity via filters + screening_questions. When unsure, make one. If you have a priced feasibility request (see terac_request_feasibility), pass its id as feasibility_request_id to price this opportunity from that confirmed CPI instead of an autonomous estimate, and Terac skips the estimate and LLM steps. The request stays RESPONDED until the draft actually launches, and only then reads WON, so a request you read back as still RESPONDED after this call has not failed to attach; an abandoned draft must not win the deal. Key fields: - title: human-facing opportunity name. - description: what the opportunity is about, shown to participants. The field and the draft both accept up to 8000 characters, but the study builder a researcher edits it in is capped at 280, so anything longer has to be cut down by hand before they can touch it there. Lead with what matters and keep it inside 280 characters. - project_id: project to file this under (from terac_list_projects / terac_create_project). - num_participants: number of completed submissions you need. - business_type: 'b2c' or 'b2b'. - tasks: ordered steps each expert performs. Each task needs sequence, task_type (interview | file_upload | activity) and review_type (auto_approve | manual_review | self_report). duration_minutes is required except on file_upload, which carries no time estimate. Pick task_type by where the answer lands: interview when you have a page they work and submit on, file_upload when the deliverable is a file, and activity ONLY when you want nothing back, because it collects nothing. Do not reach for activity just because the work is not literally an interview. With no page yet, ask the customer for one; the task is still an interview, you just cannot create it yet. None of them books a human-moderated call; that task type is not available through this API. ## Fields the customer sees that this tool cannot write candidate_profile and required_accounts are part of the audience step the researcher works through in the dashboard, and they come back on this tool's response, but there is no input for any of them here. Read the returned values rather than claiming you configured them, and say which ones need a dashboard edit when you hand the draft over. customer_screening_review also appears in that step and is writable here, so set it instead of sending the customer to the dashboard for it. ## Review Types & Payment (choose deliberately) review_type controls when the expert gets paid: - auto_approve: accepted and paid automatically, but ONLY on a task with a task_url whose provider redirects to the completion callback below. A task with no URL has no way to fire that callback, so auto_approve silently falls back to manual review there, use self_report if you want it to pay itself. - self_report: the participant attests completion, which auto-approves and PAYS them immediately. You CANNOT withhold payment based on your own quality signal. Only pick this when attestation is sufficient (e.g. low-stakes activities). - manual_review: the submission lands in AWAITING_REVIEW and is paid only when you call terac_approve_submission; terac_reject_submission withholds payment. Use this whenever you need to gate payout on your own verification or quality grading. If you want to verify work before paying, use manual_review, not self_report. ## Targeting & screening Target with filters first: apply the hard filters the request implies (country, age, gender, ...) using slugs and the exact option id values from terac_list_filters and terac_get_filter_options (country is an ISO code like GB, not United Kingdom); never invent them. Put nuanced qualifiers (roles, tools, skills, exclusions) into screening_questions. This tool REFUSES a create that sends neither filters nor unrestricted_audience: true, and refuses one that sends both. The refusal only makes you state which one you mean; it cannot tell whether you asked, so reaching for unrestricted_audience to clear the error is the one failure it is powerless to catch. - filters: structured hard filters. Each entry is { "<filter_slug>": { "<operator>": value } } using slugs/operators from terac_list_filters (e.g. { "integer--age": { "$gte": 25, "$lte": 45 } }). To target on prior participation, reference your own opportunity ids with reference--has_taken_study / reference--has_not_taken_study, using "$in" to match ANY of them or "$all" to match ALL of them. - unrestricted_audience (only without filters): true records that everyone, worldwide, at any age, in any language, is the sample the customer wants. Nothing is stored; it only makes the choice explicit. - screening_questions (optional): who gets ACCEPTED, not what the study asks. A screening question establishes that an applicant is the right fit: their experience, the tools they use, the role they hold, the context they work in. Its answers are how you tell a qualified applicant from an unqualified one, and nothing more. NEVER put the research questions here. Screening runs BEFORE an applicant is accepted and is UNPAID, so a screener carrying the study's real questions collects the answers for free from everyone who applies, including everyone you then turn away. If you find yourself writing the thing you actually want to learn, that belongs at task_url. Choice questions (pick "one" | "any" | "boolean") carry answer options with qualify_logic. On pick "one" and "boolean" only one answer can be selected, so "may", "must" and "must_one_of" all mean the same thing there and a question with no "reject" answer screens nobody out; use pick "any" when you need a disposition per answer. Set pick: "text" for an open-ended freeform question (no answers; responses route to manual review). On choice questions, add skip_rules to branch to a later question (or end the screener) based on the answer given. - quotas (optional): per-answer target counts; each quota references a screening_question key. Each target takes a type: "minimum" (a floor, the default), "maximum" (a cap - further applicants who pick that answer are screened out once it is full) or "exact". Quotas cannot target open-ended (pick: "text") questions. ## What a task_url IS (read this before choosing a task_type) A task_url is the page where the expert BOTH does the work AND submits their answer: the survey, the form, the tool you are running for them. It is not a reference to read. A repo, a document, a homepage or a chat thread is not a task, because the expert has no way to submit from it. The customer hosts that page, not Terac, and it owes the expert two things: - SHOW the material they have to work from: the scenario, the spec, the document, the questions. - Give them an INPUT to answer with: a form, a text box, a file upload, whatever fits the work. The answer is submitted to YOUR page and lands with you. Terac never sees it and cannot collect it for you; all Terac does is send the right expert there and tell you which submission they were. So if you are holding material the expert needs to read, that material belongs ON that page, not in the task description; and if you want something back from them, that page is what has to ask for it. This matters because on an interview or an activity, Terac's task screen renders a title, a duration, your description and a completion button, and NOTHING else. There is no form and no text box on it. So a task of either type with no task_url returns you only the fact that the button was pressed; whatever the expert read, decided or wrote has nowhere to go and is lost. file_upload is the one type whose screen does collect something, an uploader, and it is the exception described below. Two workarounds look reasonable and collect nothing: - Pasting the material into description. The expert can read it; they still cannot answer it. - Moving the questions into screening_questions. Screening runs BEFORE the expert is accepted and is unpaid, so this asks for the study for free and pays nobody for it. Two more things share that screen and so collect nothing either: activity, and a title carrying the instructions instead of a page that asks for the work. file_upload is the exception, and the one type that needs no task_url: the expert uploads through Terac and you read the files off the submission. So a deliverable that IS a file (a document, a recording, a screenshot) does not need you to host anything. Its screen is a real one, not the bare button. instructions renders above a drop zone, and accepted_mime_types decides what the picker will take: exact types like application/pdf, a family wildcard like image/*, or */* for anything. min_files and max_files bound how many they must attach (at most 20, both default to 1), and max_file_size_bytes caps each one (25 MB by default). The files come back on the submission, and every one of those limits reads back on the task so you can see what was actually enforced. So a deliverable the customer describes as a document, a deck, a recording, a spreadsheet, a screenshot or a portfolio is a file_upload. Pointing an interview task at some third-party upload form instead asks them to go build a page they did not need, and asking them for a URL at all is the wrong question when the answer is a file. It carries CONTEXT too, which is what makes it right for work the expert has to read before they produce anything. description renders on that screen as markdown, so a link in it is live: point them at the deck, the spec or the recording there, and have them upload what they wrote back. instructions is the plain line above the drop zone, so put what to hand back in it rather than a URL, because it does not render as a link. Do NOT set task_url on a file_upload: it is accepted and stored, the upload screen never renders it, and a link put there is one the expert never sees. Which means "read this document and tell us what you think" is a file_upload with the document linked in description. Material to read is not what makes a task need a page of yours; needing to collect an answer that is not a file is. So: if the customer wants an expert to produce anything, it goes to interview when you have a page for them, or file_upload when the answer is a file. Use activity only when there is genuinely nothing to collect. If the answer is neither a file nor something you have a page for, ask for a URL and wait; the task is still an interview, you just cannot create it yet. When you ask for that page, use words the customer already understands rather than this tool's field names. What you want is a page on their side where the expert does the task and hands the result back, in whatever form the work takes: typed, chosen, rated, recorded, uploaded. Start from their own site, product or prototype, because a customer commissioning research on something they built usually has somewhere to put it already, and a page they own is the one they can change. Raise a form builder only once they say they have nowhere, and as an example rather than a house recommendation. Say what will NOT do in the same breath, because a link they can read but not act on is exactly what they will send back: a document, a repo, a homepage, a deck. ## Task URLs & Attribution (IMPORTANT) For each task that HAS a task_url, Terac appends tracking params to it per participant so you can attribute returned work to a specific submission: - submissionId: the submission this participant is completing - teracSubmissionId: same value; the PREFERRED key (some platforms only forward known params) - taskId: the task within the submission Some hosts also receive provider-specific params. Read these from the query string at your endpoint. When the participant finishes, redirect them to https://<your-terac-host>/api/external/callback (carrying those params, e.g. as a survey completion redirect) to mark the submission complete. You can pass an optional result param (default completed; e.g. screened_out or rejected) to signal the outcome. The created opportunity echoes participant_url_template on each task: the exact URL with {submissionId}/{taskId} macros, so you can see what gets appended. Pricing: with feasibility_request_id the confirmed CPI is used; otherwise it is estimated automatically from the tasks and targeting. Review it via terac_get_opportunity before launching. Drafts below the $5 budget minimum are rejected at creation time. Note: without feasibility_request_id, this endpoint is expected to be slow (5-10 seconds). Either way, wait for this tool to return its pricing before calling terac_launch_draft_opportunity. ## Hand the draft over when it is built The response carries links.dashboard.draft_editor: the dashboard URL that opens this draft in the study builder a human reviews it in. Give the customer that URL exactly as returned, followed by a compact Markdown table headed `Before launch, please confirm`, carrying the six things that decide the money and the sample and nothing else, because a table nobody finishes reading confirms nothing: - Participants: the count. - Audience: the exact hard filters, AND the dimensions left unrestricted. - Screening: each criterion in plain language, who passes and who is turned away. - Task: what they do, and how long it takes. - Payment: when the expert gets paid, and whether anybody reviews the work first. - Cost: estimated participant incentive, platform fee, total. The rest of the setup is in the draft editor, so point there rather than listing it. An unwritable field the customer will look for is the exception: name candidate profile and required accounts as needing a dashboard edit. On the screening row, give the reason you chose each criterion, and where one could sensibly have gone the other way, name the version you did not build: somebody who meant customers who had already churned, rather than current ones, finds that out only when you show them yours. Recommend, do not survey. "Here is who I am screening for, and why, tell me if you had someone different in mind" invites the correction. Then ask one explicit confirmation question and stop there, do not launch until they say so. A summary is not a question, and 'tell me when to launch' is not one either. Say what you assumed, in the turn you assume it. The customer is reading a chat transcript, not watching a form fill in, so a value you chose is invisible until somebody opens the draft editor. Name the recruitment window, the allowed devices, the business type and the question wording as you settle them, a line each, and keep moving; do not bank them for the end. A choice mentioned while you are making it is one the customer can still redirect, and the same choice in a closing wall of text is a receipt. One more nobody picked, and it belongs beside the table because nothing else will surface it: an AI screening interview runs on every study that has a screener. State it, do not ask about it. Applicant review is yours to set: `customer_screening_review` defaults to `auto_invite`, so say which one the draft carries, and send `manual_review` when the customer wants a say in who takes part. Describe only what you actually sent. Read your own filters back out of this response before you write that summary and name them literally. Calling the sample "US freelancers" when the only filter you set was employment status invents a restriction the study has not got, and that is worse than saying nothing: an omission leaves the customer free to notice, a false claim answers the question before they ask it.

Create a project to group related opportunities. Projects keep an organization's work organized; pass the returned project ID as project_id to terac_create_opportunity.

Decline an applicant from terac_get_applicants. They are not invited, never reach the task, and the submission becomes screened_out. This ends that expert's participation in the opportunity and tells them they were not selected, so it is not the way to defer a decision: leaving them in the queue is. A `reason` is optional on the wire and recorded on the submission's history for your own team; give one, because a decline with no reason leaves nothing for a later question to be answered from. Returns CONFLICT when the applicant is not awaiting a decision, which includes one already decided.

Delete a draft opportunity. Only opportunities in DRAFT or CREATING status can be deleted, to end a launched opportunity use terac_stop_opportunity instead.

List the applicants waiting on a decision before they can start the task. An opportunity on customer_screening_review=manual_review sends every qualified applicant here; one on auto_invite still sends the individuals a screener answer graded `review`, so poll it either way. They are absent from terac_get_submissions and terac_get_submission returns NOT_FOUND for them: they have passed the screener but hold no submission status until you decide. Each row carries the screening_answers that decision is made from. Resolve one with terac_invite_applicant or terac_decline_applicant; either way they leave this queue and appear in terac_get_submissions. Nothing announces an arrival, so poll on the same cadence as terac_get_submissions, and report the queue depth rather than sitting on it: an applicant nobody decides on is an expert waiting indefinitely.

IMPORTANT: Call this tool FIRST before using any other Terac tool. ## What is Terac? Terac is the human labor MCP. When your agent needs a real human to do something, interview an expert, test a product, label data, verify a claim, grade a deliverable, or provide domain expertise, Terac finds the right person, screens them, manages the task, verifies completion, and handles payment. Think of it as the bridge between AI agents and the real world of human skill and opinion. Terac owns and operates a vetted expert panel spanning every industry and geography. You define WHAT you need done and WHO should do it. Terac handles the rest: recruiting, screening, task delivery, quality grading, and payout. ## What This Tool Returns A markdown summary of your authenticated organization including: - Organization identity (name, slug, ID) - Current balance (calculated from the ledger, reflects the environment your API key is connected to) - All projects in the organization - Opportunity counts by status - Dashboard URLs, absolute links into the researcher dashboard where a human reviews and controls this work: the organization's home, its opportunities, its drafts, its feasibility requests, where it tops up its balance, and where it manages API keys. Every project row carries its own URL too. Hand these to the customer instead of a bare id; they almost certainly have the dashboard open. Use them exactly as returned, the host and the route shape both come from the response, never from a pattern you assemble. - Organization Policies, org-specific instructions. If present, these are non-negotiable constraints set by the org admin. You MUST embed them into every task and panel specification you create. These may include required consent language, mandatory demographic quotas, geographic restrictions, budget thresholds, prohibited topics, or approval workflows. No org policies in the response means there are none to apply: proceed, and do NOT ask the customer for guidelines, consent language, privacy or compliance requirements. An org admin sets those, not them. ## Core Workflow Every engagement follows this sequence: 1. **Call terac_get_context** (this tool) to understand your org, balance, and policies. 2. **Align with the user.** Understand what they want to learn before you build. The operating guide in this tool's result sorts every study value into what you ask for, what you propose and then get confirmed, and what you simply assume. Read terac_create_opportunity's own description before you build with it. 3. **Price and build the draft.** Pick one of the paths in "Ways to Launch" below: request feasibility (human-confirmed price) or build a draft with explicit targeting. Either way you end up with a DRAFT, which costs nothing and starts no recruitment. 4. **Hand the draft to the customer.** Give them the draft's links.dashboard.draft_editor URL and the confirmation block terac_create_opportunity specifies, so they can review the whole setup. 5. **Launch once they confirm.** Launching commits real money and begins recruitment. A draft you built with terac_create_opportunity carries its own screener and materials already, so it goes straight to ACTIVE with no preparation phase in between. 6. **Confirm it is recruiting.** The launch response already carries the new status, so there is nothing to wait out; read progress from terac_get_opportunity from here on. 7. **Monitor submissions** (terac_get_submissions). As experts complete the task, submissions appear. Check periodically, recruitment is asynchronous and can take minutes to days depending on panel difficulty. 8. **Review results.** Read each submission's screening answers, qualification status, and task deliverables, then approve (terac_approve_submission) or reject (terac_reject_submission) each submission that is AWAITING_REVIEW. Approving pays the expert; rejecting requires a reason. ## Ways to Launch Two ways to price and build an opportunity. Both end at a draft you hand over, and both commit real money only at the launch the customer asks for; they differ in how the price is set and how much you specify up front: 1. **Feasibility** (Terac confirms the price): terac_request_feasibility -> terac_get_feasibility_request -> terac_create_opportunity (with feasibility_request_id) -> hand over links.dashboard.draft_editor -> (customer confirms) -> terac_launch_draft_opportunity. Terac confirms the CPI; you create the opportunity with that confirmed price. 2. **Draft-first** (full control): terac_create_opportunity (define tasks, structured filters, screening questions, and quotas explicitly) -> hand over links.dashboard.draft_editor -> (customer confirms) -> terac_launch_draft_opportunity. Use when you need precise targeting via terac_list_filters / terac_get_filter_options rather than a free-text panel description. Neither arrow chain skips the hand-off. ## Opportunity Lifecycle DRAFT --> ACTIVE --> FULFILLED --> COMPLETED | ^ | | +---------+ (FULFILLED auto-reopens to ACTIVE if approvals drop below target) | |---> PAUSED --> ACTIVE (via terac_resume_opportunity) | +---> STOPPED (permanent, irreversible, via terac_stop_opportunity) - DRAFT: built and priced, but nothing is charged and nobody is recruited until you launch it. An opportunity Terac is still preparing for itself (the REST quote-launch flow, which is not one of these tools) also reads as draft; status has no separate value for it. - ACTIVE: Recruitment is running. Submissions will appear over time. - PAUSED: Recruitment suspended. In-progress submissions unaffected. - FULFILLED: Target submission count reached; in a short grace window before COMPLETED. New applicants are blocked. Terac auto-reopens it to ACTIVE if approved submissions later drop below target (e.g. after a rejection); this is the self-healing quota. You CANNOT pause or stop a FULFILLED opportunity (those require ACTIVE or PAUSED); let it settle to COMPLETED. - COMPLETED: All target submissions delivered. - STOPPED: Permanently ended. Unused budget refunded. Cannot be restarted. - PRE_RECRUITING, EXPIRED, CANCELLED and FAILED sit outside that flow and cannot be launched, edited or deleted. terac_get_opportunity says what each one means. ## Async by Nature (Poll for Results) Progress is polled, not pushed. After launching an opportunity, real humans are recruited, scheduled, and complete tasks. This takes time: minutes to hours to days depending on the audience and timeline you specified. Poll for results: - Every 5-15 minutes for active opportunities - Every 30-60 minutes for large or niche audiences Read aggregate progress from submission_stats on terac_get_opportunity, and the per-submission list from terac_get_submissions. The opportunity continues running on Terac's side whether or not you are polling. If your runtime has idle limits, inform the user that results will take time and offer to check back. ## Important Details - Self-serve limits on participant count and the recruitment window are in this tool's result, beside the rest of the capability limits. Larger needs require contacting sales. - Field naming: targetSubmissionCount in the API maps to targetResponseCount internally. Same value. - Only non-deleted opportunities are returned in listings. - The transcript field on submissions is null unless the organization is on the transcript whitelist. ## Tool Quick Reference | Tool | Purpose | |------|---------| | terac_get_context | Org identity, balance, projects, policies (call first) | | terac_list_projects | List projects for organizing opportunities | | terac_create_project | Create a project to group opportunities | | terac_get_project | Get a project's details and opportunity count | | terac_update_project | Rename a project | | terac_list_filters | List structured targeting filters (demographic, geographic, professional) | | terac_get_filter_options | List the allowed values for a filter (e.g. countries, industries) | | terac_request_feasibility | Submit a feasibility request (task + panel); returns a request id to poll | | terac_get_feasibility_request | Poll a feasibility request for its confirmed price | | terac_list_feasibility_requests | List your org's feasibility requests | | terac_create_opportunity | Create a draft opportunity directly (tasks, filters, screeners, quotas) | | terac_update_opportunity | Edit a draft opportunity (copy, count, tasks, filters, screener + quotas) | | terac_launch_draft_opportunity | Launch a draft created via terac_create_opportunity | | terac_delete_opportunity | Delete a draft opportunity | | terac_list_opportunities | List all opportunities with status and counts | | terac_get_opportunity | Get opportunity details, screeners, and progress | | terac_pause_opportunity | Suspend recruitment (reversible, free) | | terac_resume_opportunity | Restart paused recruitment | | terac_stop_opportunity | Permanently end recruitment (irreversible, refunds unused budget) | | terac_get_submissions | Get all reviewable submissions for an opportunity | | terac_get_submission | Get one submission's details | | terac_approve_submission | Approve a submission awaiting review (pays the expert) | | terac_reject_submission | Reject a submission awaiting review (with category + reason) |

Retrieve one of your feasibility requests by ID. This is how you learn the price: read status, and read costPerParticipant, which is null until the request is priced. ## Read the status before you read the price Five values, and only one of them means you have a price: - RECEIVED: not priced yet. costPerParticipant is null and there is no price to report. - RESPONDED: priced. costPerParticipant is the confirmed all-in CPI per participant. Create the opportunity with terac_create_opportunity (pass feasibility_request_id) and launch it with terac_launch_draft_opportunity. - WON: this request already priced a study that launched. It is spent; do not attach it to a new draft. - LOST or NOT_PURSUED: closed without a usable price. Both are TERMINAL. Nothing further will arrive, so stop polling. On a terminal status the response carries no reason, so you do not know whether the audience was unsourceable, the timeline impossible, or the request simply closed. Tell the customer it came back without a price, do not invent why, and offer the next real move: build the draft for an estimated price, re-scope the audience and request feasibility again, or ask us via the dashboard_url. ## Polling cadence Poll once as soon as you have the id, before waiting at all: many requests are already priced by then, and sleeping first only adds that delay to the customer's wait. If it is still RECEIVED, poll every couple of minutes for the first fifteen, then back off to every fifteen to thirty. Past that a person is pricing it and it may take hours; polling harder will not help and there is no webhook to wait on. If your runtime cannot stay open that long, say so, hand over the dashboard_url so the customer can watch the price land, and offer to pick it back up. Do not fill the gap with a number.

List the allowed values for a single filter (e.g. the list of countries, industries, or seniorities). Results are paginated and searchable. Geographic filters cascade: for states pass country_id, and for cities pass country_id (and optionally state_id). Use the returned option ids as filter values when building an opportunity's `filters`.

Get full details for an opportunity: id, title, status, num_participants (your target), estimated_duration_minutes, pricing, filters, screening_questions (with qualify_logic), tasks (with participant_url_template), and device_types. Once launched it also includes submission_stats (total / in_progress / awaiting_review / approved / rejected) for at-a-glance progress, quota_progress (per-segment approvals when you set quotas, each carrying the target's type so you can tell whether current approaching count means a cap is about to close or a floor is about to be met), and links to related endpoints. links.dashboard carries this study's pages in the researcher dashboard. When you report on an opportunity, give the customer the URL that matches what you are telling them, draft_editor for a draft they still have to review, submissions for progress on a launched one, rather than only its id. ## Reading a Screener Back screening_questions comes back in the shape terac_create_opportunity accepts, so you can send it straight back on an update. Two fields read back normalized rather than verbatim, and neither is an error to "fix": - qualify_logic on a single-select (pick "one", which is also how a yes/no question reads back) is always "must" for any qualifying answer, because "may", "must" and "must_one_of" mean the same thing when only one answer can be picked. A "may" you sent reading back as "must" is what is stored; rewriting it to "may" will not make the question filter. Use "reject" to screen out, or pick "any" for per-answer logic. - A quota target stored without a type reads back as "exact", because that is how enforcement treats an untyped quota. That is about quotas stored that way (older or dashboard-authored ones), not about what you sent: a type you write is stored and reads back unchanged, and omitting it on write stores "minimum". ## Polling for Status Use this tool to poll for status transitions. Key patterns: - After launching: nothing to poll for. A draft you launch is already active in the launch response. - While ACTIVE: poll every 5-15 minutes and read submission_stats to track progress vs num_participants. For large or niche audiences, poll every 30-60 minutes. - The opportunity continues running on Terac's side regardless of whether you are polling. - If your runtime has idle limits, inform the user that results will take time and offer to check back. ## Opportunity Lifecycle State Machine DRAFT --> ACTIVE --> FULFILLED --> COMPLETED | ^ | | +---------+ (FULFILLED auto-reopens to ACTIVE if approvals drop below target) | |---> PAUSED --> ACTIVE (via terac_resume_opportunity) | +---> STOPPED (permanent, irreversible) - DRAFT: built and priced; nothing charged and nobody recruited until you launch it. An opportunity Terac is still preparing from a REST quote also reads as draft; status has no separate value for it. - ACTIVE: Recruitment is running. Submissions appear over time. - PAUSED: Recruitment suspended. In-progress submissions unaffected. - FULFILLED: Target submission count reached; in a short grace window before COMPLETED. New applicants are blocked. Terac auto-reopens it to ACTIVE if approved submissions drop below target (the self-healing quota). It cannot be paused or stopped. - COMPLETED: All target submissions delivered. - STOPPED: Permanently ended. Unused budget refunded. Cannot be restarted. Outside that flow, and none can be launched, edited or deleted (status reads each in lowercase): - PRE_RECRUITING: Taking applicants ahead of a launch set up in the dashboard, charged only when it launches there. terac_stop_opportunity is the only tool that applies. - EXPIRED: Its recruitment window closed before the target was reached. Ended. - CANCELLED: Ended by Terac, unused budget refunded. - FAILED: Its launch from a REST quote never finished, and no tool can change it. Create a new opportunity; pricing shows anything that was charged. Valid transitions: - terac_pause_opportunity: ACTIVE -> PAUSED - terac_resume_opportunity: PAUSED -> ACTIVE - terac_stop_opportunity: ACTIVE, PAUSED, or PRE_RECRUITING -> STOPPED - ACTIVE -> FULFILLED -> COMPLETED happens automatically; FULFILLED and COMPLETED accept no manual transitions (you cannot pause or stop them). - Invalid transitions return a CONFLICT error.