Research (R1)

The Research Agent is our flagship agent. It is a very powerful tool that you can use to research your customers and prospects. R1 has access to a large set of tools to get information. Which tools it uses depends on the user's request.

On this page, we'll dive into the R1 endpoints you can use to trigger the Research Agent programmatically.

POST/v1/agents/runs

Initiate a Research run

This endpoint allows you to initiate a research run of the R1 agent.

Required attributes

Name
agent
Type
enum['r1', 'r1-light']
Description
The agent to run. Must be r1 or r1-light. r1 is a more powerful agent that has access to a larger set of research sources, whereas r1-light is a more affordable version of R1.
Name
lead
Type
Lead
Description
The lead to research. See the Lead type for more information.

Optional attributes

Name
max_research_steps
Type
integer
Description
In case you'd like to limit R1 to a maximum amount of research steps, you can do so here. Defaults to 5.
Name
context
Type
string
Description
The context for the research run. This is a free-form string that will be used to guide R1's research.
Name
user
Type
User
Description
The user that is initiating the research run. Defaults to the user information that we have on file for the API key. Handy in case you're researching on behalf of another company. See the User type for more information.
Name
events
Type
[]Event
Description
Any previous events that have happened which are relevant for R1 to use as context. See the Event type for more information.
Name
metadata
Type
Record<string, string>
Description
Free-format metadata that will be stored with the research run. You can use this to store any information you want to associate with the research run. There can be up to 100 keys. The key must be less than 100 characters and the value must be less than 1000 characters.
Name
callback_url
Type
string
Description
The URL to call when the research run is completed. The URL will receive a POST request with the research run result (the same body as the response of the GET /v1/agents/runs/:run endpoint).
Name
use_memory
Type
boolean
Description
Whether the agent should remember and potentially use information gained from previous runs. Recommended in case you're running multiple agent runs on the same lead and you'd like to prevent duplicate research.

Returns

Name
id
Type
string
Description
The ID of the created research run.

Request

POST

/v1/agents/runs

curl -X POST https://api.utopianlabs.ai/v1/agents/runs \
  -H "Authorization: Bearer {token}" \
  -H "Content-Type: application/json" \
  -d '{
    "agent": "r1",
    "lead": {
      "company": {
        "website": "example.com",
        "name": "Example Corp"
      },
      "person": {
        "full_name": "John Smith",
        "job_title": "CEO"
      }
    },
    "max_research_steps": 5,
    "context": "Looking for potential partnership opportunities"
  }'

Response

{
  "id": "abc123"
}

GET/v1/agents/runs/:run

Retrieve Research Run Status

This endpoint allows you to retrieve the status of a research run. In case the research run is completed, you will receive a list of research results.

Returns

Name
created_at
Type
number
Description
The timestamp of when the research run was created in milliseconds since the Unix epoch.
Name
id
Type
string
Description
The id of the research run.
Name
status
Type
enum['queued', 'running', 'failed', 'completed']
Description
The status of the research run.
Name
agent
Type
enum['r1', 'r1-light']
Description
The agent that was used to run the research.
Name
error
Type
string
Description
The error that occurred during the research run, if any.
Name
result
Type
ResearchResult
Description
The result of the research run, if any. See the ResearchResult type for more information.
Name
metadata
Type
Optional<Record<string, string>>
Description
Free-format metadata that will be stored with the research run. You can use this to store any information you want to associate with the research run. There can be up to 100 keys. The key must be less than 100 characters and the value must be less than 1000 characters.

Request

GET

/v1/agents/runs/:run

curl https://api.utopianlabs.ai/v1/agents/runs/abc123 \
  -H "Authorization: Bearer {token}"

Response

{
  "created_at": 1736337711557,
  "id": "abc123",
  "agent": "r1",
  "status": "completed",
  "result": {
    "research": {
      "conclusion": "An elaborate research report",
      "steps": [
        {
          "action": "I searched for customer reviews online",
          "outcome": "An elaboration on what R1 did and found"
        }
      ]
    }
  }
}