> 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.orbitfin.ai/orbit-api-reference/api/agent-builder.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.