R1-Timing

The Timing Agent is used to determine the right timing to contact a lead. If you want to contact a lead, both for the first time or to revive a deal, the Timing Agent helps you to determine the right timing. When necessary, it can invoke the Research Agent to get the relevant information to determine the timing.

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

POST/v1/agents/runs

Initiate a Timing run

This endpoint allows you to initiate a timing run of the R1-Timing agent.

Required attributes

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

Optional attributes

Name
max_research_steps
Type
integer
Description
In case you'd like to limit R1-Timing to a maximum amount of research steps, you can do so here. Defaults to 5.
Name
context
Type
string
Description
The context for the timing 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 timing 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-Timing 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 timing 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 timing run is completed. The URL will receive a POST request with the timing 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 timing 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-timing",
    "lead": {
      "company": {
        "website": "example.com",
        "name": "Example Corp"
      },
      "person": {
        "full_name": "John Smith",
        "job_title": "CEO"
      }
    },
    "max_research_steps": 5,
    "context": "This lead asked me to contact him in 6 months. It has been 3 months now, is this the right time to contact them again?"
  }'

Response

{
  "id": "abc123"
}

GET/v1/agents/runs/:run

Retrieve Timing Run Status

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

Returns

Name
created_at
Type
number
Description
The timestamp of when the timing run was created in milliseconds since the Unix epoch.
Name
id
Type
string
Description
The id of the timing run.
Name
status
Type
enum['queued', 'running', 'failed', 'completed']
Description
The status of the timing run.
Name
agent
Type
enum['r1-timing', 'r1-timing-light']
Description
The agent that was used to run the research.
Name
error
Type
string
Description
The error that occurred during the timing run, if any.
Name
result
Type
TimingResult
Description
The result of the timing run, if any. See the TimingResult type for more information.
Name
metadata
Type
Optional<Record<string, string>>
Description
Free-format metadata that will be stored with the timing run. You can use this to store any information you want to associate with the timing 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-timing",
  "status": "completed",
  "result": {
    "research": {
      "conclusion": "An elaborate research report",
      "steps": [
        {
          "action": "I searched for open job positions for the customer's company.",
          "outcome": "An elaboration on what R1 did and found"
        }
      ]
    },
    "timing": {
      "score": "high",
      "reason": "This is the perfect time to contact this lead again, because they just opened a job position for a VP of Sales."
    }
  }
}