Append a run to a thread

Add a new question to an existing Research thread and receive a separate asynchronous run. Use this route when the next angle belongs with the evidence you have already collected instead of starting another collection.

POST/api/v1/research/threads/{encrypted_id}/run

API keyAPI key with research:write

Required boundary headers

x-api-key or Authorization: BearerIdempotency-Key

Overview

What this route does

Use the encrypted thread token returned by create or portfolio reads to continue an investigation without creating a second collection.

Contract

Request parameters

Request body

Only fields in this request contract are accepted. The route ignores no undocumented shape and uses these fields to keep the work bounded and predictable.

promptRequiredstring

The question that gives the investigation its direction and keeps each source artifact tied to the caller's goal. Keep it between 1 and 20,000 characters so the request remains focused and bounded.

request_schema_versionOptional1 | 2

Selects the request shape the service should interpret. Use version 2 when sending reference_artifact_ids, because explicit prior-artifact context is supported only by that contract version.

Default: 2

sizeOptionalsmall | medium | large

Chooses a preset level of source coverage and discovery effort for the run. Use it when a simple capacity choice is more useful than setting each target separately; the supported values map to 15, 50, or 100 sources.

target_sourcesOptionalinteger

Sets how many sources the investigation should try to examine. The value can be from 1 through 1,000, keeping the requested scope visible and bounded before work starts.

search_callsOptionalinteger

Sets how many discovery calls the run may make while looking for useful material. The value can be from 1 through 100, giving the investigation a clear search effort limit.

resource_kindsOptionalpaper[] | web[]

Chooses whether the investigation searches scholarly papers, general web resources, or both. At least one and no more than two implemented values may be supplied, and the default includes both surfaces.

Default: ["paper", "web"]

source_sitesOptionalstring[]

Suggests reviewed source sites that should influence discovery. These are soft preferences, so unknown site values may be ignored rather than preventing the rest of the run from completing.

include_domainsOptionalstring[]

Limits discovery to approved hostname-only entries. You may provide up to 50 values, and the list is also checked against exclude_domains so the request does not contradict itself.

exclude_domainsOptionalstring[]

Keeps selected hostname-only entries out of discovery. You may provide up to 50 values, and none may overlap include_domains because a domain cannot be both required and excluded.

published_afterOptionalYYYY-MM-DD

Favors material published after the supplied calendar date. The value must be a real date in YYYY-MM-DD format so the filter has an unambiguous meaning.

languageOptionalstring

Tells discovery which language should be preferred when selecting material. Values must be between 2 and 12 characters, and the default is en.

Default: en

max_run_cost_centsOptionalinteger

Sets the maximum budget the run may use before additional work is stopped or requires approval. The value can be from 1 through 100,000 cents, making the spending boundary visible before execution.

provider_keysOptionalstring[]

Names server-side provider-key references that the service may resolve for the run. These are references rather than secrets, so raw provider credentials must never be placed in a public request.

reference_artifact_idsOptionalencrypted_id[]

Adds a deliberate set of previously saved artifacts as context for the next investigation. Supply up to 15 unique encrypted public tokens and use request schema version 2; the service does not load every old artifact automatically.

Examples

Request and response

Example request

curl -X POST "https://vidbyte-backend.onrender.com/api/v1/research/threads/rth_public_token/run" \
  -H "x-api-key: $VIDBYTE_API_KEY" \
  -H "Idempotency-Key: research-append-001" \
  -H "Content-Type: application/json" \
  -d '{"prompt":"Compare the strongest counter-evidence"}'

Example response

{
  "encrypted_id": "rth_public_token",
  "run_id": "rrun_append_example",
  "status": "accepted"
}

Response

Response and errors

Returns 202 Accepted with the existing encrypted_id and the new run_id.
Prior artifact bodies are not automatically injected into the next model context.