R1-Qualification

The Qualification Agent is used to determine the ICP fit of the lead in the request. You can use it to evaluate the relevancy of a company and/or a person. When necessary, it can invoke the Research Agent to get the relevant information to qualify a company.

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

POST/v1/agents/runs

Initiate a Qualification run

This endpoint allows you to initiate a qualification run of the R1-Qualification agent.

Required attributes

Name
agent
Type
enum['r1-qualification', 'r1-qualification-light']
Description
The agent to run. Must be r1-qualification or r1-qualification-light. r1-qualification uses the default research agent, which has access to a larger set of research sources, whereas r1-qualification-light uses the light research agent to make it more affordable.
Name
lead
Type
Lead
Description
The lead to qualify. See the Lead type for more information.

Optional attributes

Name
max_research_steps
Type
integer
Description
In case you'd like to limit R1-Qualification to a maximum amount of research steps, you can do so here. Defaults to 5.
Name
context
Type
string
Description
The context for the qualification 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 qualification 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-Qualification 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 qualification 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 qualification run is completed. The URL will receive a POST request with the qualification 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 qualification 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-qualification",
    "lead": {
      "company": {
        "website": "example.com",
        "name": "Example Corp"
      },
      "person": {
        "full_name": "John Smith",
        "job_title": "CEO"
      }
    },
    "max_research_steps": 5,
    "context": "We're solely looking for SaaS businesses that either recently hired a CRO or are expanding their sales team"
  }'

Response

{
  "id": "abc123"
}

GET/v1/agents/runs/:run

Retrieve Qualification Run Status

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

Returns

Name
created_at
Type
number
Description
The timestamp of when the qualification run was created in milliseconds since the Unix epoch.
Name
id
Type
string
Description
The id of the qualification run.
Name
status
Type
enum['queued', 'running', 'failed', 'completed']
Description
The status of the qualification run.
Name
agent
Type
enum['r1-qualification', 'r1-qualification-light']
Description
The agent that was used to run the research.
Name
error
Type
string
Description
The error that occurred during the qualification run, if any.
Name
result
Type
QualificationResult
Description
The result of the qualification run, if any. See the QualificationResult type for more information.
Name
metadata
Type
Optional<Record<string, string>>
Description
Free-format metadata that will be stored with the qualification run. You can use this to store any information you want to associate with the qualification 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-qualification",
  "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"
        }
      ]
    },
    "qualification": {
      "score": "high",
      "reason": "The lead has a high qualification score because they have a large website and a strong online presence."
    }
  }
}