R1-Classification

The Classification Agent is used to classify leads based on predefined options. When necessary, it can invoke the Research Agent to get the relevant information to classify a company.

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

POST/v1/agents/runs

Initiate a Classification run

This endpoint allows you to initiate a classification run of the R1-Classification agent.

Required attributes

Name
agent
Type
enum['r1-classification', 'r1-classification-light']
Description
The agent to run. Must be r1-classification or r1-classification-light. r1-classification uses the default research agent, which has access to a larger set of research sources, whereas r1-classification-light uses the light research agent to make it more affordable.
Name
lead
Type
Lead
Description
The lead to classify. See the Lead type for more information.
Name
options
Type
[]{ name: string, description: string }
Description
The options to classify the lead into. A minimum of 2 options is required. You can provide up to 10 options.

Optional attributes

Name
max_research_steps
Type
integer
Description
In case you'd like to limit R1-Classification to a maximum amount of research steps, you can do so here. Defaults to 5.
Name
context
Type
string
Description
The context for the classification 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 classification 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-Classification 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 classification run. You can use this to store any information you want to associate with the classification 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 classification run is completed. The URL will receive a POST request with the classification 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 classification 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-classification",
    "lead": {
      "company": {
        "website": "example.com",
        "name": "Example Corp"
      },
      "person": {
        "full_name": "John Smith",
        "job_title": "CEO"
      }
    },
    "options": [
      {
        "name": "SaaS",
        "description": "A software-as-a-service business"
      },
      {
        "name": "Agency",
        "description": "A business that provides services to other businesses"
      }
    ],
    "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 Classification Run Status

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

Returns

Name
created_at
Type
number
Description
The timestamp of when the classification run was created in milliseconds since the Unix epoch.
Name
id
Type
string
Description
The id of the classification run.
Name
status
Type
enum['queued', 'running', 'failed', 'completed']
Description
The status of the classification run.
Name
agent
Type
enum['r1-classification', 'r1-classification-light']
Description
The agent that was used to run the classification.
Name
error
Type
string
Description
The error that occurred during the classification run, if any.
Name
result
Type
ClassificationResult
Description
The result of the classification run, if any. See the ClassificationResult type for more information.
Name
metadata
Type
Optional<Record<string, string>>
Description
Free-format metadata that will be stored with the classification run. You can use this to store any information you want to associate with the classification 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"
        }
      ]
    },
    "classification": {
      "choice": "SaaS",
      "reason": "The reasoning behind the choice"
    }
  }
}