> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sequentum.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Build your first agent with Agent Builder and pull structured data — in under five minutes.

In this quickstart you'll:

1. Authenticate API requests with your Sequentum API key.
2. Open an Agent Builder session and describe the data you want.
3. Poll until the build completes.
4. Run the agent and download extracted data.

<Note>
  You'll need a Sequentum account and an API key. Generate an API key from your [Sequentum dashboard](https://dashboard.sequentum.com/user/api-keys). Keys start with `sk-`.
</Note>

## 1. Set your API key

<CodeGroup>
  ```python python theme={null}
  import os
  os.environ["SEQUENTUM_API_KEY"] = "sk-..."
  ```

  ```ts ts theme={null}
  process.env.SEQUENTUM_API_KEY = "sk-...";
  ```

  ```bash cURL theme={null}
  export SEQUENTUM_API_KEY="sk-..."
  ```
</CodeGroup>

## 2. Start an Agent Builder session

Describe the agent you want in plain language. Agent Builder will plan, build, and test it for you.

<CodeGroup>
  ```python python theme={null}
  import os, requests

  r = requests.post(
      "https://dashboard.sequentum.com/api/v1/agent-builder/start",
      headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
      json={
          "prompt": "Pull product name, price, and SKU from https://example-store.com/products/",
      },
  )
  session = r.json()
  session_id = session["sessionId"]
  print(session_id)
  ```

  ```ts ts theme={null}
  const r = await fetch("https://dashboard.sequentum.com/api/v1/agent-builder/start", {
    method: "POST",
    headers: {
      Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Pull product name, price, and SKU from https://example-store.com/products/",
    }),
  });
  const session = await r.json();
  const sessionId = session.sessionId;
  console.log(sessionId);
  ```

  ```bash cURL theme={null}
  curl https://dashboard.sequentum.com/api/v1/agent-builder/start \
    -H "Authorization: ApiKey $SEQUENTUM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Pull product name, price, and SKU from https://example-store.com/products/"
    }'
  ```
</CodeGroup>

The response gives you a `sessionId`. Agent Builder is now planning, executing, and testing on Sequentum's side.

```json theme={null}
{
  "sessionId": "ab_123..."
}
```

## 3. Wait for the build

Poll `GET /agent-builder/{sessionId}/status` every few seconds until `status` is `completed`. The response then carries `agentId` — that's your new Agent's id.

<CodeGroup>
  ```python python theme={null}
  import os
  import time
  import requests

  while True:
      r = requests.get(
          f"https://dashboard.sequentum.com/api/v1/agent-builder/{session_id}/status",
          headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
      )
      body = r.json()
      if body["status"] == "completed":
          agent_id = body["agentId"]
          break
      if body["status"] == "error":
          raise RuntimeError(body.get("error", "build failed"))
      time.sleep(5)
  ```

  ```ts ts theme={null}
  let agentId: number | null = null;
  while (!agentId) {
    const r = await fetch(
      `https://dashboard.sequentum.com/api/v1/agent-builder/${sessionId}/status`,
      { headers: { Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}` } }
    );
    const body = await r.json();
    if (body.status === "completed") {
      agentId = body.agentId;
      break;
    }
    if (body.status === "error") throw new Error(body.error ?? "build failed");
    await new Promise((res) => setTimeout(res, 5000));
  }
  ```

  ```bash cURL theme={null}
  while true; do
    RESP=$(curl -s "https://dashboard.sequentum.com/api/v1/agent-builder/$SESSION_ID/status" \
      -H "Authorization: ApiKey $SEQUENTUM_API_KEY")
    STATUS=$(echo "$RESP" | jq -r .status)
    if [ "$STATUS" = "completed" ]; then
      AGENT_ID=$(echo "$RESP" | jq -r .agentId)
      echo "Agent built: $AGENT_ID"
      break
    elif [ "$STATUS" = "error" ]; then
      echo "Build failed: $RESP"
      exit 1
    fi
    sleep 5
  done
  ```
</CodeGroup>

When the build succeeds, the status response includes the new Agent id:

```json theme={null}
{
  "status": "completed",
  "agentId": 12345
}
```

<Tip>
  Builds typically complete in one to two minutes for simple sites. Complex sites with auth, pagination, or anti-bot challenges can take longer. You can manually monitor the progress in your organization's AI Agents page [https://dashboard.sequentum.com/org/ai-agents](https://dashboard.sequentum.com/org/ai-agents). If the build returns an `error`, inspect the response body — most failures are due to a vague prompt; revise and start a new session.
</Tip>

## 4. Start a run

Start the agent asynchronously. The response returns a Run id you can poll.

<CodeGroup>
  ```python python theme={null}
  r = requests.post(
      f"https://dashboard.sequentum.com/api/v1/agent/{agent_id}/start",
      headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
      json={"isRunSynchronously": False},
  )
  run = r.json()
  run_id = run["id"]
  print(run_id)
  ```

  ```ts ts theme={null}
  const r = await fetch(`https://dashboard.sequentum.com/api/v1/agent/${agentId}/start`, {
    method: "POST",
    headers: {
      Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ isRunSynchronously: false }),
  });
  const run = await r.json();
  const runId = run.id;
  console.log(runId);
  ```

  ```bash cURL theme={null}
  RUN_ID=$(curl -s "https://dashboard.sequentum.com/api/v1/agent/$AGENT_ID/start" \
    -X POST \
    -H "Authorization: ApiKey $SEQUENTUM_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{ "isRunSynchronously": false }' | jq -r .id)

  echo "$RUN_ID"
  ```
</CodeGroup>

## 5. Wait for the run

Poll run status until the Run is finished. `Completed` and `Success` mean the Run finished successfully.

<CodeGroup>
  ```python python theme={null}
  FINISHED = {6, 8, 9, 10, 11, "Failure", "Stopped", "Completed", "Success", "Skipped"}
  SUCCESSFUL = {9, 10, "Completed", "Success"}

  while True:
      r = requests.get(
          f"https://dashboard.sequentum.com/api/v1/agent/{agent_id}/run/{run_id}/status",
          headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
      )
      run = r.json()
      if run["status"] in FINISHED:
          if run["status"] not in SUCCESSFUL:
              raise RuntimeError(f"Run did not complete successfully: {run}")
          break
      time.sleep(5)
  ```

  ```ts ts theme={null}
  const finished = new Set([6, 8, 9, 10, 11, "Failure", "Stopped", "Completed", "Success", "Skipped"]);
  const successful = new Set([9, 10, "Completed", "Success"]);

  while (true) {
    const r = await fetch(
      `https://dashboard.sequentum.com/api/v1/agent/${agentId}/run/${runId}/status`,
      { headers: { Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}` } }
    );
    const run = await r.json();

    if (finished.has(run.status)) {
      if (!successful.has(run.status)) {
        throw new Error(`Run did not complete successfully: ${JSON.stringify(run)}`);
      }
      break;
    }

    await new Promise((res) => setTimeout(res, 5000));
  }
  ```

  ```bash cURL theme={null}
  while true; do
    RUN=$(curl -s "https://dashboard.sequentum.com/api/v1/agent/$AGENT_ID/run/$RUN_ID/status" \
      -H "Authorization: ApiKey $SEQUENTUM_API_KEY")
    STATUS=$(echo "$RUN" | jq -r .status)

    case "$STATUS" in
      9|10|Completed|Success)
        break
        ;;
      6|8|11|Failure|Stopped|Skipped)
        echo "$RUN"
        exit 1
        ;;
    esac

    sleep 5
  done
  ```
</CodeGroup>

## 6. List output files

After the Run finishes, list its output files and choose a file to download.

<CodeGroup>
  ```python python theme={null}
  files_response = requests.get(
      f"https://dashboard.sequentum.com/api/v1/agent/{agent_id}/run/{run_id}/files",
      headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
  )
  files = files_response.json()
  file_id = files[0]["id"]
  file_name = files[0].get("name") or f"run-{run_id}-output"
  ```

  ```ts ts theme={null}
  const filesResponse = await fetch(
    `https://dashboard.sequentum.com/api/v1/agent/${agentId}/run/${runId}/files`,
    { headers: { Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}` } }
  );
  const files = await filesResponse.json();
  const fileId = files[0].id;
  const fileName = files[0].name ?? `run-${runId}-output`;
  ```

  ```bash cURL theme={null}
  FILES=$(curl -s "https://dashboard.sequentum.com/api/v1/agent/$AGENT_ID/run/$RUN_ID/files" \
    -H "Authorization: ApiKey $SEQUENTUM_API_KEY")

  FILE_ID=$(echo "$FILES" | jq -r '.[0].id')
  FILE_NAME=$(echo "$FILES" | jq -r '.[0].name // "run-output"')
  ```
</CodeGroup>

## 7. Download an output file

Download endpoints redirect to the file content. Follow redirects when saving the file.

<CodeGroup>
  ```python python theme={null}
  download_response = requests.get(
      f"https://dashboard.sequentum.com/api/v1/agent/{agent_id}/run/{run_id}/file/{file_id}/download",
      headers={"Authorization": f"ApiKey {os.environ['SEQUENTUM_API_KEY']}"},
  )

  with open(file_name, "wb") as f:
      f.write(download_response.content)
  ```

  ```ts ts theme={null}
  import { writeFile } from "node:fs/promises";

  const downloadResponse = await fetch(
    `https://dashboard.sequentum.com/api/v1/agent/${agentId}/run/${runId}/file/${fileId}/download`,
    { headers: { Authorization: `ApiKey ${process.env.SEQUENTUM_API_KEY}` } }
  );

  await writeFile(fileName, Buffer.from(await downloadResponse.arrayBuffer()));
  ```

  ```bash cURL theme={null}
  curl -L "https://dashboard.sequentum.com/api/v1/agent/$AGENT_ID/run/$RUN_ID/file/$FILE_ID/download" \
    -H "Authorization: ApiKey $SEQUENTUM_API_KEY" \
    -o "$FILE_NAME"
  ```
</CodeGroup>

## What's next

<CardGroup cols={2}>
  <Card title="Agent Builder sessions" icon="wand-magic-sparkles" href="/agent-builder/sessions">
    Status polling, the agentId handoff, and stopping a build.
  </Card>

  <Card title="Schedule recurring runs" icon="calendar" href="/api-reference/schedules/list">
    Attach a run-once, interval, or advanced schedule to any agent.
  </Card>

  <Card title="Run lifecycle" icon="circle-play" href="/concepts/runs">
    Statuses, stopping runs, and what every run produces.
  </Card>
</CardGroup>