> For the complete documentation index, see [llms.txt](https://docs.orbitfin.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.orbitfin.ai/orbit-api-reference/api/agent-builder.md).

# Agent Builder

`GET /v1/agent_builder/list` — List all active Agent Builders owned by the current user. `POST /v1/agent_builder/outputs` — Fetch artifacts (structured data or HTML report) for a given `agent_id`.

Authentication\*\*: Both endpoints require user authentication. The user is identified from the request context; do **not** pass `user_id` in the request. Rate limit\*\*: `2 req/s` per endpoint.

### 1. List Agent Builders

`GET /v1/agent_builder/list`

Returns all **active** Agent Builders owned by the current user, ordered by creation time (latest first).

Request

No request parameters. The user identity is resolved from the authentication context.

````
```http
GET /v1/agent_builder/list
Authorization: Bearer <token>
```

### Response

On success, `data` is an array of Agent Builders. Each item contains:

| Field | Type | Description |
|---|---|---|
| `id` | string | Agent Builder ID. Use this value as `agent_id` when calling the `outputs` endpoint. |
| `name` | string | Builder display name. |
| `description` | string \| null | Builder description. |
| `field_mapping` | object | Field-extraction schema: group → field → metadata (label, type, description, etc.). Extracted values are **not** included here; fetch them via the `outputs` endpoint. |
| `created_at` | datetime | Builder creation time. |
| `company_list` | object[] | Companies bound to this builder. Each item: `{orbit_entity_id, name}`. Empty array when no company is configured. |
| `subscriptions` | object[] | Active subscriptions attached to this builder (see table below). Empty array when no active subscription exists. |

`subscriptions[]` item fields:

| Field | Type | Description |
|---|---|---|
| `ag_sub_id` | string | Subscription ID. |
| `agent_category` | string | `AgentBuilder-Data` or `AgentBuilder-Report`. |
| `subscription_name` | string | Subscription display name. |
| `schedule_cron_expression` | string | Cron expression that triggers the subscription. |

### Errors

| Status | Message | Description |
|---|---|---|
| `404` | Agent builder info not found | The current user has no active Agent Builder. |

### Example
{
  "data": [
    {
      "id": "ab_01HXXXX...",
      "name": "Quarterly Earnings Extractor",
      "description": "Extract key financial metrics from 10-Q filings.",
      "field_mapping": {
        "financials": {
          "revenue": { "label": "Revenue", "type": "number", "description": "Total revenue (USD)" },
          "net_income": { "label": "Net Income", "type": "number", "description": "Net income (USD)" }
        }
      },
      "created_at": "2026-04-12T08:31:22Z",
      "company_list": [
        { "orbit_entity_id": "OE_0001", "name": "Apple Inc." },
        { "orbit_entity_id": "OE_0002", "name": "Microsoft Corp." }
      ],
      "subscriptions": [
        {
          "ag_sub_id": "sub_01HYYYY...",
          "agent_category": "AgentBuilder-Data",
          "subscription_name": "Daily 10-Q sweep",
          "schedule_cron_expression": "0 6 * * *"
        }
      ]
    }
  ]
}
````

### **2. Get Agent Builder Outputs**

`POST /v1/agent_builder/outputs`

Returns artifacts produced by a specific Agent Builder, ordered by `publish_date` (latest first). **Pagination is mandatory** — every call must explicitly specify `limit` and `offset`.

````
Request

```http
POST /v1/agent_builder/outputs
Content-Type: application/json
Authorization: Bearer <token>
```

Request body:

| Field | Type | Required | Description |
|---|---|---|---|
| `agent_id` | string | yes | Agent Builder ID, obtained from the `list` endpoint. |
| `agent_type` | string | yes | `data` returns extracted structured data; `report` returns the HTML report URL. |
| `limit` | integer | **yes** | Maximum number of artifacts to return, range `1–50`. No implicit default. |
| `offset` | integer | **yes** | Pagination offset, `>= 0`. Pass `0` for the first page. |
| `orbit_entity_id_list` | string[] | no | Optional company filter. Effective only when `agent_type=data`; returns artifacts whose `orbit_entity_id` is in this list. Ignored when `agent_type=report`. |

> ⚠️ Every value in `orbit_entity_id_list` must originate from the `company_list` of the same builder returned by the `list` endpoint. Arbitrary external IDs are not allowed.

### Response

On success, `data` is an array of artifacts. The field set depends on `agent_type`.

**Common fields**:

| Field | Type | Description |
|---|---|---|
| `id` | string | Artifact ID. |
| `publish_date` | date | Publish date of the artifact. |
| `created_at` | datetime | Row creation time. |
| `company_list` | object[] | Companies associated with this artifact: `{orbit_entity_id, name}`. `data` artifacts typically contain a single company; `report` artifacts may contain multiple. |

**When `agent_type = data`**:

| Field | Type | Description |
|---|---|---|
| `extract_json` | object | Structured data extracted by the agent according to the builder's field schema. |

**When `agent_type = report`**:

| Field | Type | Description |
|---|---|---|
| `url` | string | Publicly accessible URL of the HTML report. |

### Errors

| Status | Message | Description |
|---|---|---|
| `404` | Agent builder meta not found | No artifact matches the given `agent_id` + `agent_type`. |
| `422` | Validation error | `limit` out of range, `offset < 0`, invalid `agent_type`, etc. |

### Example — `data`

```json
// Request
{
  "agent_id": "ab_01HXXXX...",
  "agent_type": "data",
  "limit": 20,
  "offset": 0,
  "orbit_entity_id_list": ["OE_0001"]
}
```

```json
// Response
{
  "data": [
    {
      "id": "art_01HZZZZ...",
      "publish_date": "2026-05-01",
      "created_at": "2026-05-01T03:11:45Z",
      "company_list": [
        { "orbit_entity_id": "OE_0001", "name": "Apple Inc." }
      ],
      "extract_json": {
        "financials": {
          "revenue": 124300000000,
          "net_income": 33000000000
        }
      }
    }
  ]
}
```

### Example — `report`

```json
// Request
{
  "agent_id": "ab_01HXXXX...",
  "agent_type": "report",
  "limit": 10,
  "offset": 0
}
```

```json
// Response
{
  "data": [
    {
      "id": "art_01HAAAAA...",
      "publish_date": "2026-05-10",
      "created_at": "2026-05-10T09:00:12Z",
      "company_list": [
        { "orbit_entity_id": "OE_0001", "name": "Apple Inc." },
        { "orbit_entity_id": "OE_0002", "name": "Microsoft Corp." }
      ],
      "url": "https://oassets.orbitfin.ai/reports/2026-05-10/ab_01HXXXX.html"
    }
  ]
}
````

**Typical Workflow**

1. Call `GET /v1/agent_builder/list` to retrieve the current user's Agent Builders. Pick the target `agent_id` and collect the available `orbit_entity_id` values from `company_list`.
2. Decide which artifact form to fetch:
   * `agent_type=data` — Retrieve structured extraction results; optionally filter by `orbit_entity_id_list`.
   * `agent_type=report` — Retrieve the HTML report URL.
3. Call `POST /v1/agent_builder/outputs` with mandatory `limit` (1–50) and `offset` (≥0); increment `offset` to paginate.

***

**Rate Limit & Pagination**

* Per-endpoint rate limit: `2 req/s`.
* Pagination parameters on `outputs` are **mandatory** and have no default; increment `offset` for subsequent pages.