Start research task

Starts a deep research task that runs multiple searches, reads sources, and synthesizes an answer with citations.

Synchronous mode (default)

When background is false or omitted, the request blocks until the research completes and returns the answer with citations. This can take up to 120 seconds depending on research_effort.

Asynchronous mode

When background is true, the request returns immediately with a task_id and status: pending. Poll GET /web_search/research/{task_id} to check when the research completes and retrieve the answer.

POST

web_search

research

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.webSearch.research.create({
  query: 'Compare the performance of RAG vs fine-tuning for domain-specific QA',
});

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.web_search.research.create(
    query="Compare the performance of RAG vs fine-tuning for domain-specific QA",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	research, err := client.WebSearch.Research.New(
		context.TODO(),
		telnyx.WebSearchResearchNewParams{
			Query: "Compare the performance of RAG vs fine-tuning for domain-specific QA",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", research.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.webSearch.research.ResearchCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        ResearchCreateParams params = ResearchCreateParams.builder()
            .query("Compare the performance of RAG vs fine-tuning for domain-specific QA")
            .build();
        var response = client.webSearch().research().create(params);
    }
}

require "telnyx"

telnyx = Telnyx::Client.new(api_key: "My API Key")

response = telnyx.web_search.research.create(query: "Compare the performance of RAG vs fine-tuning for domain-specific QA")

puts(response)

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->webSearch->research->create(
    query: 'Compare the performance of RAG vs fine-tuning for domain-specific QA',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/web_search/research \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "Compare the performance of RAG vs fine-tuning for domain-specific QA",
  "research_effort": "standard",
  "max_sources": 20,
  "background": false
}
'

{
  "data": {
    "answer": "RAG and fine-tuning serve different purposes...",
    "citations": [
      {
        "url": "https://arxiv.org/abs/2401.15884",
        "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
        "snippet": "We show that RAG models produce more factually grounded responses..."
      }
    ]
  }
}

Authorizations

Authorization

string

header

required

Telnyx API key

Body

application/json

query

string

required

The research question or topic.

Required string length: 1 - 2000

Example:

"Compare the performance of RAG vs fine-tuning for domain-specific QA"

research_effort

enum<string>

Research depth level. lite is fastest, deep is most thorough.

Available options:

lite,

standard,

deep

Example:

"standard"

max_sources

integer

Maximum number of sources to use.

Required range: 1 <= x <= 50

Example:

20

background

boolean

When true, the research runs asynchronously. The response returns a task_id immediately instead of waiting for the result. Poll GET /web_search/research/{task_id} to check status.

Example:

false

Response

Research response. Shape depends on background:

Synchronous (background false/unset): returns answer + citations.
Asynchronous (background true): returns task_id + status.

data

object

Synchronous research response (when background is false or unset).

Option 1
Option 2

Show child attributes

JavaScript

import Telnyx from 'telnyx';

const client = new Telnyx({
  apiKey: process.env['TELNYX_API_KEY'], // This is the default and can be omitted
});

const response = await client.webSearch.research.create({
  query: 'Compare the performance of RAG vs fine-tuning for domain-specific QA',
});

console.log(response.data);

import os
from telnyx import Telnyx

client = Telnyx(
    api_key=os.environ.get("TELNYX_API_KEY"),  # This is the default and can be omitted
)
response = client.web_search.research.create(
    query="Compare the performance of RAG vs fine-tuning for domain-specific QA",
)
print(response.data)

package main

import (
	"context"
	"fmt"

	"github.com/team-telnyx/telnyx-go"
	"github.com/team-telnyx/telnyx-go/option"
)

func main() {
	client := telnyx.NewClient(
		option.WithAPIKey("My API Key"),
	)
	research, err := client.WebSearch.Research.New(
		context.TODO(),
		telnyx.WebSearchResearchNewParams{
			Query: "Compare the performance of RAG vs fine-tuning for domain-specific QA",
		},
	)
	if err != nil {
		panic(err.Error())
	}
	fmt.Printf("%+v\n", research.Data)
}

package com.telnyx.sdk.example;

import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import com.telnyx.sdk.models.webSearch.research.ResearchCreateParams;

public final class Main {
    private Main() {}

    public static void main(String[] args) {
        TelnyxClient client = TelnyxOkHttpClient.fromEnv();

        ResearchCreateParams params = ResearchCreateParams.builder()
            .query("Compare the performance of RAG vs fine-tuning for domain-specific QA")
            .build();
        var response = client.webSearch().research().create(params);
    }
}

require "telnyx"

telnyx = Telnyx::Client.new(api_key: "My API Key")

response = telnyx.web_search.research.create(query: "Compare the performance of RAG vs fine-tuning for domain-specific QA")

puts(response)

<?php

require_once dirname(__DIR__) . '/vendor/autoload.php';

use Telnyx\Client;
use Telnyx\Core\Exceptions\APIException;

$client = new Client(apiKey: getenv('TELNYX_API_KEY') ?: 'My API Key');

try {
  $response = $client->webSearch->research->create(
    query: 'Compare the performance of RAG vs fine-tuning for domain-specific QA',
  );

  var_dump($response);
} catch (APIException $e) {
  echo $e->getMessage();
}

curl --request POST \
  --url https://api.telnyx.com/v2/web_search/research \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "query": "Compare the performance of RAG vs fine-tuning for domain-specific QA",
  "research_effort": "standard",
  "max_sources": 20,
  "background": false
}
'

{
  "data": {
    "answer": "RAG and fine-tuning serve different purposes...",
    "citations": [
      {
        "url": "https://arxiv.org/abs/2401.15884",
        "title": "Retrieval-Augmented Generation for Knowledge-Intensive NLP Tasks",
        "snippet": "We show that RAG models produce more factually grounded responses..."
      }
    ]
  }
}

Web Search

Features

API Reference

For AI Agents

Start research task

Synchronous mode (default)

Asynchronous mode

Authorizations

Body

Response