> ## Documentation Index > Fetch the complete documentation index at: https://docs.cassidyai.com/llms.txt > Use this file to discover all available pages before exploring further. # Pull usage analytics with the Admin API > Create an Admin API key and pull organization-wide usage, Workflow runs, Agent chats, meetings, and Audit Logs into your own reports and dashboards. The Admin API lets admins pull the same usage analytics shown on the Analytics dashboard, plus lists of Workflow runs, Agent chats, meetings, and [Audit Logs](https://docs.cassidyai.com/settings/audit-logs.md) events, into spreadsheets, BI tools, or scheduled reports. > [!NOTE] > > The Admin API is available on **Enterprise** plans and needs to be enabled by > our team. [Contact us](mailto:support@cassidyai.com) if you require access. > You need the **Manage Admin Keys** privilege, which admins have by default. > See [roles and groups](https://docs.cassidyai.com/settings/roles-and-groups.md). ## Admin API keys vs. API keys Admin API keys act as your organization, not as a user. They aren't tied to anyone's permissions, keep working when the person who created them leaves, and can only call the Admin API, which reads organization-wide data. [API keys](https://docs.cassidyai.com/agents/deploy/api.md) work the other way around. They act as the user who created them, with that user's permissions, and let your applications chat with your Agents. Use an API key to call Cassidy as a specific user, and an Admin API key to report on your whole organization. ## Create an Admin API key **1. Open the Admin Keys settings** Go to **Organization settings** and select **Admin Keys** under **API**. ![Admin Keys settings page with no keys and the Create Admin key button in the top-right corner](https://mintcdn.com/cassidy/y-v7MhTNtEm06xdn/images/settings/admin-api-settings.png?fit=max\&auto=format\&n=y-v7MhTNtEm06xdn\&q=85\&s=efde6ae9b696990fbfe7519b9295218b) **2. Create a key** Click **Create Admin key** and give the key a name that says where it is used. Choose its [permissions](#permissions) and when it [expires](#expiration), then click **Create key**. ![Create Admin key dialog with Expiration set to Never and Restricted permissions with only Analytics selected](https://mintcdn.com/cassidy/y-v7MhTNtEm06xdn/images/settings/admin-api-create-key.png?fit=max\&auto=format\&n=y-v7MhTNtEm06xdn\&q=85\&s=1482ae9407b6f1d83f8525cf22080ddf) **3. Copy the key** Copy the key and store it somewhere only admins can reach. Cassidy shows it once. If you lose it, revoke it and create a new one. > [!WARNING] > > An Admin API key reads data for your whole organization, including by person > and group. Treat it like a password. ## Permissions Each key can call only the endpoints its permissions allow. Calling any other endpoint returns `403` with the permission it needs. Choose **All** to grant every permission available to your organization, or **Restricted** to pick them one at a time. Give each key only what its job needs. For example, a usage dashboard only needs **Analytics**. | Permission | Scope | Endpoints | | - | - | - | | Analytics | `analytics:read` | `/metrics/timeseries`, `/metrics/breakdown` | | Workflow runs | `workflow_runs:read` | `/workflow-runs` | | Chats | `chats:read` | `/chats` | | Meetings | `meetings:read` | `/meetings` | | Audit logs | `audit_logs:read` | `/audit-logs` | Admin API keys are read-only. They can't change anything in your organization. A key's permissions can't be changed after you create it. To change them, create a new key and revoke the old one. ## Expiration Keys never expire unless you choose an expiration when you create them: 30, 60, or 90 days, 1 year, or a custom date. The **Admin Keys** page shows when each key expires and flags keys that expire within 7 days. Requests with an expired key return `401`. ## Make your first request Send the key as a bearer token. This request returns daily credits for September 2026: ```bash theme={null} curl -G 'https://app.cassidyai.com/api/admin/v1/metrics/timeseries' \ -H 'Authorization: Bearer YOUR_ADMIN_API_KEY' \ --data-urlencode 'metric=credits' \ --data-urlencode 'unit=day' \ --data-urlencode 'from=2026-09-01T00:00:00Z' \ --data-urlencode 'to=2026-10-01T00:00:00Z' ``` Each endpoint has its own page in the API reference with its parameters, limits, and response format. ## Download the API specification Your organization's OpenAPI specification describes every endpoint available to it. Use it to load the API into another tool, such as Postman or a code generator: ```bash theme={null} curl 'https://app.cassidyai.com/api/admin/v1/openapi.json' \ -H 'Authorization: Bearer YOUR_ADMIN_API_KEY' ``` Admins can also browse it on the **Endpoints** tab of **Organization settings** > **Admin Keys**. ## What you can do ### Measure usage `/metrics/timeseries` charts a metric over time, by hour, day, week, or month. `/metrics/breakdown` totals a metric over a period for each user, group, Agent, Workflow, or source, so you can see who and what uses Cassidy most, and where people chat with Agents, such as Slack or Microsoft Teams. | Metric | What it counts | | - | - | | `credits` | Credits used across your organization | | `meetingHours` | Hours of meetings recorded | | `meetings` | Meetings recorded | | `chatMessages` | Messages sent to [Agents](https://docs.cassidyai.com/agents/overview.md) | | `workflowRuns` | [Workflow](https://docs.cassidyai.com/workflows/overview.md) runs | You can narrow either one to a person, a group, a Workflow, a source, or specific Agents or models. ### Measure meeting usage `meetingHours` counts each recorded meeting once, from when the notetaker starts recording until it stops. This is the total you're billed for, and it includes meetings that were deleted later. Each meeting is attributed to one member, the person who first added the notetaker. To see who joined each meeting, use [`/meetings`](#list-meetings). ### List Workflow runs `/workflow-runs` lists individual [Workflow](https://docs.cassidyai.com/workflows/overview.md) runs with who started them, their status, and the credits they used. Filter by Workflow or person, or leave out test runs. ### List chats `/chats` lists Agent chats with their Agent, who started them, where they happened (such as Slack or a website embed), and the credits they used. Filter by person, Agent, model, or source. A chat's Agent is the one most recently used in it, and Agent and model filters match that Agent. Analytics count each reply under the Agent that wrote it, so when people switch Agents mid-chat, the same Agent filter can select different activity in `/chats` than in `/metrics`. ### List meetings `/meetings` lists recorded meetings with their hours, who added the notetaker, which members joined, and how many other people joined. Filter by person to list the meetings they joined. Deleted meetings aren't listed. ### List audit logs `/audit-logs` lists the same events as the [Audit Logs](https://docs.cassidyai.com/settings/audit-logs.md) page, so you can archive them or analyze them in your own tools. Filter by category, person, resource, or type of operation. Events are newest first unless you pass `order=asc`. List endpoints return one page at a time. Pass each response's `nextCursor` as `cursor` to get the next page. ## Send audit logs to your SIEM For security information and event management (SIEM) tools that can poll a REST API on a schedule, use polling mode to fetch new events from `/audit-logs`. Start with `order=asc` and a `from` date, and leave out `to`: ```bash theme={null} curl -G 'https://app.cassidyai.com/api/admin/v1/audit-logs' \ -H 'Authorization: Bearer YOUR_ADMIN_API_KEY' \ --data-urlencode 'order=asc' \ --data-urlencode 'from=2026-10-01T00:00:00Z' ``` Save the response's `nextCursor`, and pass it as `cursor` on every later request. When you leave out `to`, `nextCursor` is always returned, even when there are no new events, so your tool can keep polling from where it stopped. Poll every few minutes, and keep any filters the same on every request. * **Events may appear up to 2 minutes late.** * **Use `id` to remove duplicates.** If your tool retries a request with the same cursor, it can receive the same events again. * **If your tool sends its own `from` and `to`, end each window a few minutes in the past.** The 2-minute delay only applies when you leave out `to`, so a window that ends now can miss events that are still being recorded. Each call to `/audit-logs` records an audit log export event. Those events are filtered out of results for the Admin key that made the call. Other keys and the Audit Logs page still show them. ## Credits on records vs. analytics > [!WARNING] > > Adding up the credits on individual runs and chats may not match the totals > from `/metrics` for the reasons below. Use `/metrics` for credit totals. The `credits` metric also includes other usage that isn't a chat or a Workflow run, such as meeting recordings, file parsing, and more. To compare like with like, use the `agent` or `workflow` breakdown of `credits`, which count only Agent chats or only Workflow runs. Even then, the totals may differ because: * **Deleted chats and Workflow runs aren't listed**, but the credits they used still count in analytics. * **Some chats aren't listed.** `/chats` leaves out chats run by Workflows and Agent test chats. * **Ranges work differently.** Lists count each chat's or run's credits in the range it started, while analytics counts credits on the day they were used. ## Rate limits Each key can make 60 requests per minute, and all of your organization's keys together can make 300. When you exceed a limit, the API responds with `429` and a `Retry-After` header. Recent results refresh every few minutes, and older ranges are cached for up to an hour. ## Revoke a key On the **Admin Keys** settings page, click the trash icon next to the key and confirm. Requests using the key stop working immediately. Creating, revoking, and using keys is recorded in [Audit Logs](https://docs.cassidyai.com/settings/audit-logs.md). This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.