# Org Export API

Pull conversations, usage, and session metadata across every app in your organization with a single API key.

---

The Org Export API is a read-only REST API scoped to your **entire organization** rather than a single app. Use it to pull all your chat transcripts, usage data, and session metadata into a warehouse (Snowflake, BigQuery, Postgres) or to run attribution analysis on a schedule.

> **Note:** The [Builder API](/docs/builder-api/overview) covers one app at a time. The Org Export API covers all apps in your org with one key and one pull loop. If you are running a separate agent per client, this is the endpoint that gives you a portfolio view.

## Authentication

Mint an org-level key from the dashboard under **Settings**, or ask the Alchemist:

> "Create an org read API key with the transcripts and usage scopes."

Send the key as a Bearer token on every request:

```
Authorization: Bearer YOUR_ORG_KEY
```

Rate limit: 120 requests per minute per key. A `429` response includes `Retry-After`.

### Scopes

Each key carries one or more read scopes. Requests outside a key's scopes return `403`:

| Scope | Grants |
|-------|--------|
| `apps:read` | List the org's apps. |
| `transcripts:read` | Read chat sessions and messages. |
| `usage:read` | Read token usage and cost rows. |

Mint separate keys per consumer. A warehouse sync job needs `transcripts:read` and `usage:read`. A billing script needs only `usage:read`.

## Pagination

List endpoints are cursor-paginated, newest first:

- `?limit=` (default 50, max 100).
- Follow `pagination.next_cursor` until `pagination.has_more` is `false`.
- For incremental syncs, filter by time (`started_after`, `since`) and keep the maximum `started_at` or `created_at` seen as the checkpoint for the next run.

```json
"pagination": { "next_cursor": "eyJ...", "has_more": true, "limit": 50 }
```

## Endpoints

### List apps

```
GET /api/v1/org/apps
```

Returns the org's apps, non-deleted, newest first.

```bash
curl -s "https://app.avcodex.com/api/v1/org/apps" \
  -H "Authorization: Bearer $AVCODEX_ORG_KEY"
```

```json
{
  "data": [
    {
      "id": "uuid",
      "name": "MVCC Sales Onboarding Agent",
      "slug": "mvcc-onboarding-8jw2",
      "created_at": "2026-04-19T02:33:55.787Z",
      "updated_at": "2026-06-04T23:55:47.228Z"
    }
  ]
}
```

### List sessions

```
GET /api/v1/org/sessions
```

Cursor-paginated chat sessions across all apps. Filter with `started_after` for incremental pulls.

### Read usage

```
GET /api/v1/org/usage
```

Token usage and cost rows across all apps. Filter with `since`.

## Why integrators use this

If you deploy an agent per client, per-app analytics answer "how is this one doing" but never "how is the book of business doing." The Org Export API is what turns a set of separate deployments into a managed service you can actually report on.

Three practical builds:

- **Client value reporting.** Pull session counts per app per month, join to your client list, and generate the renewal deck automatically instead of screenshotting dashboards.
- **Margin tracking.** Usage rows give you token cost per app. If you bill a flat monthly rate per agent, this is how you find the client whose agent is quietly eating the margin.
- **Cross-client pattern detection.** Transcripts across every deployment show which questions recur everywhere. Those are the ones worth building into your standard knowledge base, or productizing.

## Incremental sync pattern

Do not re-pull everything on every run. Store the highest `started_at` you have seen, then request only newer records:

1. Read the checkpoint from your last run.
2. Request the first page with `started_after` set to that checkpoint.
3. Page through with `next_cursor` until `has_more` is false.
4. Write the new maximum `started_at` back as the checkpoint.

Run it nightly. A full re-pull will hit the rate limit once you have any real volume.

## Data handling

Transcripts contain whatever your end users typed, which in a support context regularly includes names, email addresses, phone numbers, and internal system details. Once you export them to a warehouse, they fall under your own data retention and privacy obligations, not the platform's. Set a retention policy on the warehouse tables before you turn the sync on, not after.

*AVCodex · Your AV expertise. Amplified by AI.*