---
title: Quickstart
description: Create and poll your first Research Agent task.
sidebar:
  icon: rocket
  hidden: true
---

Research runs asynchronously. Creating a task returns immediately with a URL you can poll for the result.

## 1. Set your credentials

Keep your token and agent ID in server-side environment variables:

```bash
export SIBI_ACCESS_TOKEN="<YOUR_ACCESS_TOKEN>"
export RESEARCH_AGENT_ID="<AGENT_ID>"
```

## 2. Create a research task

```bash Curl
curl --request POST \
  "https://agents.sibi.ai/api/agents/${RESEARCH_AGENT_ID}/tasks/create" \
  --header "Authorization: Bearer ${SIBI_ACCESS_TOKEN}" \
  --header "Content-Type: application/json" \
  --data '{"message":"GE GTS18GTHWW"}'
```

```javascript JavaScript
const taskResponse = await fetch(
  `https://agents.sibi.ai/api/agents/${process.env.RESEARCH_AGENT_ID}/tasks/create`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.SIBI_ACCESS_TOKEN}`,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ message: 'GE GTS18GTHWW' }),
  },
);

if (!taskResponse.ok) {
  throw new Error(`Task creation failed: ${taskResponse.status}`);
}

const task = await taskResponse.json();
```

The API responds with `202 Accepted`:

```json
{
  "status": "pending",
  "taskId": "<TASK_ID>",
  "statusUrl": "https://agents.sibi.ai/api/agents/<AGENT_ID>/tasks/<TASK_ID>"
}
```

## 3. Poll the status URL

Send authenticated `GET` requests to the exact `statusUrl` from the response.

```bash Curl
curl \
  --header "Authorization: Bearer ${SIBI_ACCESS_TOKEN}" \
  "https://agents.sibi.ai/api/agents/${RESEARCH_AGENT_ID}/tasks/<TASK_ID>"
```

```javascript JavaScript
const resultResponse = await fetch(task.statusUrl, {
  headers: {
    Authorization: `Bearer ${process.env.SIBI_ACCESS_TOKEN}`,
  },
});

if (!resultResponse.ok) {
  throw new Error(`Task lookup failed: ${resultResponse.status}`);
}

const result = await resultResponse.json();
```

While the research is running, the response remains:

```json
{
  "status": "pending",
  "taskId": "<TASK_ID>"
}
```

Continue until `status` is `complete` or `failed`.

## 4. Read the result

A completed single-product task includes the interpreted product and its candidate replacements:

```json
{
  "status": "complete",
  "taskId": "<TASK_ID>",
  "taskUrl": "https://agents.sibi.ai/agents/<AGENT_ID>/tasks/<TASK_ID>",
  "productBeingReplaced": {
    "manufacturer": "GE",
    "model": "GTS18GTHWW",
    "description": "Top-freezer refrigerator",
    "specifications": "Capacity, dimensions, finish, electrical requirements, and features",
    "imageUrl": "https://example.com/ge-gts18gthww.jpg"
  },
  "candidateReplacements": [
    {
      "manufacturer": "Example Manufacturer",
      "model": "EXAMPLE-18W",
      "description": "Comparable top-freezer refrigerator",
      "specifications": "Capacity, dimensions, finish, electrical requirements, and features",
      "msrp": 899,
      "sibiProductId": "sibi-example-EXAMPLE-18W",
      "sibiManufacturer": "example",
      "sibiPrice": 849,
      "sibiCheckoutLink": "https://checkout.sibipro.com/...",
      "matchReasoning": "Comparable form factor, capacity, finish, and installation requirements.",
      "availableOnSibi": true,
      "imageUrl": "https://example.com/example-18w.jpg"
    }
  ]
}
```

The values above are illustrative. See [Result objects](/research-agent/results) for the complete field contract and batch response shape.

**[Understand task states](/research-agent/task-lifecycle)**

Handle pending, clarification, complete, and failed tasks.

**[Open the API reference](/research-agent/api-reference)**

Inspect every operation, schema, and generated code sample.