> ## Documentation Index > Fetch the complete documentation index at: https://docs.heliyos.ai/llms.txt > Use this file to discover all available pages before exploring further. # List credit usage > Returns the workspace's credit charges, newest first. Each entry says when credits were spent, by which feature, how many, and on what. Use it to reconcile your balance or to see what a worker run cost. This list pages by page number: send `page` and `limit`. `meta.pagination` carries `page`, `limit`, `offset` (rows skipped), `count` (all matching entries) and `hasMore`. There is no cursor. To total a period, page through every entry for it and add up `creditsUtilized`. Filters combine with AND. The API is read-only for usage: there is no way to add, change or refund credits through it. > [!NOTE] > > In the Heliyos MCP server: [`heliyos_usage_get`](https://docs.heliyos.ai/mcp/tools/usage#heliyos-usage-get). ## OpenAPI ````yaml /api-reference/openapi.json get /v1/platform/usage openapi: 3.0.3 info: title: Heliyos API version: 1.0.0 description: >- The REST API for Heliyos, the AI operating system for revenue. Every request is scoped to the workspace that owns the API key. Responses are JSON in a `{ meta, data }` envelope; errors use `{ message, error: { code, message, details } }`. contact: name: Heliyos support email: soham@heliyos.ai url: https://www.heliyos.ai servers: - url: https://api-prod.heliyos.ai description: Production security: - bearerAuth: [] tags: - name: Workspace description: >- The workspace your API key belongs to, and the log of credits it has used. Every other call in this API is scoped to this workspace. - name: Schemas description: >- Objects are your record types: companies, people, deal pipelines and any custom objects you add. Each object has fields, and a field's type decides what its records can hold. - name: Records description: >- Records are the rows of an object (base schema): companies, people, deals and custom objects. A record holds field values keyed by the object's field keys and links to other records. - name: Timeline description: >- The AI-written timeline of a company, person or deal: summary entries Heliyos writes on a schedule. For the exact change history see Activities, and for emails and meetings see Interactions. - name: Activities description: >- The change history of records and tasks: who created, changed or deleted what, and when. People, workers and the system each appear as the actor on the changes they make. - name: Interactions description: >- Email threads and meetings synced from connected mailboxes and calendars, linked to the people and companies they involve. - name: Notes description: >- Free-text notes, optionally linked to records, tasks and interactions. Notes show up on the timeline of every record they are linked to, and workers read them as customer memory. - name: Tasks description: >- Work items for people and workers, optionally linked to records. A task can be assigned to people, to workers, or both, and workers can be started on it directly. - name: Workers and runs description: >- Workers are the AI teammates of your workspace (the API calls them agents). Define what each one does and what starts it, ask Heliyos to do work, and follow every run, its steps and the reviews it waits on. - name: Reviews description: >- Reviews keep the team in control of consequential work. When a worker wants to send an email, change a deal, book a meeting, act in a connected app or needs a person's answer, the action waits as a review until someone approves or rejects it. - name: Scouts description: >- Scouts watch companies and the web for events such as funding rounds, product launches, leadership changes or press coverage, and record each finding as a signal. A workspace Scout defines what to look for; company Scouts are its copies running on individual companies. - name: Signals description: >- Signals are what Scouts find: one event, such as a funding round or a new executive, with a summary, its sources and the company it is about. New signals are unread until you mark them read. - name: Watchlist description: >- The watchlist is the set of companies your workers monitor. Each watched company uses one Watcher from your plan: the workers keep it enriched, pull in its emails and meetings, and run Scouts on it. - name: Knowledge base description: >- What your workers know about the business: the business context, four fixed texts (products, pain points, value proposition, qualification criteria) and any custom entries your team adds. Workers read it on their next run. Files your workers read live under Files, with kind `knowledge_base`. - name: Files description: >- Knowledge base files that workers read, and files attached to records, tasks and other resources. The API calls them attachments. Uploading takes three calls: get an upload URL, send the bytes to it, then create the file. - name: Labels description: >- Label groups that sort your email threads, for example Intent or Pricing questions. Heliyos files each classified thread under a group, and each group holds the more specific labels it brings together. The API calls them classification labels. - name: Team description: >- The people in your workspace and their roles: joined members and pending invitations. Inviting someone sends them an email. - name: Notification settings description: >- Which workspace events send notification emails, how often, and to whom. There is one settings document per workspace, shared by everyone in it. paths: /v1/platform/usage: get: tags: - Workspace summary: List credit usage description: >- Returns the workspace's credit charges, newest first. Each entry says when credits were spent, by which feature, how many, and on what. Use it to reconcile your balance or to see what a worker run cost. This list pages by page number: send `page` and `limit`. `meta.pagination` carries `page`, `limit`, `offset` (rows skipped), `count` (all matching entries) and `hasMore`. There is no cursor. To total a period, page through every entry for it and add up `creditsUtilized`. Filters combine with AND. The API is read-only for usage: there is no way to add, change or refund credits through it. operationId: listUsage parameters: - name: limit in: query required: false schema: type: integer minimum: 1 maximum: 100 default: 20 description: Entries per page, 1 to 100. Defaults to 20. example: 50 - name: page in: query required: false schema: type: integer minimum: 1 description: The page to return, starting at 1. Defaults to 1. example: 1 - name: from in: query required: false schema: type: string format: date-time description: >- Only entries recorded at or after this time, as an ISO 8601 date or date-time. A date alone means midnight UTC at the start of that day. example: '2026-10-01T00:00:00Z' - name: to in: query required: false schema: type: string format: date-time description: >- Only entries recorded at or before this time, as an ISO 8601 date or date-time. A date alone means midnight UTC at the start of that day, so to include a whole day send the next day's midnight or `T23:59:59.999Z`. example: '2026-10-31T23:59:59.999Z' - name: feature in: query required: false schema: type: string maxLength: 100 description: >- Only entries for this feature, exact match and case-sensitive, for example `worker_run` or `company_enrichment`. See `feature` on the entry for the values. example: worker_run - name: objectId in: query required: false schema: type: string maxLength: 100 description: >- Only entries charged on this object, exact match. For a worker run, pass the run id. example: 9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e - name: search in: query required: false schema: type: string maxLength: 200 description: >- Case-insensitive text matched against `feature`, `objectId`, `objectType` and `description`. Up to 200 characters. An empty string is ignored. example: enrichment responses: '200': description: A page of usage entries. content: application/json: schema: type: object required: - meta - data properties: meta: type: object required: - message properties: message: type: string description: A human-readable summary of the result. pagination: $ref: '#/components/schemas/OffsetPagination' data: type: array items: $ref: '#/components/schemas/UsageEntry' example: meta: message: Usage logs fetched successfully pagination: page: 1 limit: 20 offset: 0 count: 2 hasMore: false data: - _id: 6721c0a4b5d6e7f8a9b0c1d2 organizationId: 66a0f1e2d3c4b5a697887766 feature: worker_run creditsUtilized: 5 objectId: 9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e objectType: orchestrator_run sourceService: agent description: >- worker account_researcher in run 9f2c4e7a1b3d4f6a8c0e2b4d6f8a0c1e metadata: workerId: 6720f3a1b2c3d4e5f6a7b8c9 tool: account_researcher meta: organizationId: 66a0f1e2d3c4b5a697887766 feature: worker_run sourceService: agent createdAt: '2026-11-04T10:12:40.000Z' - _id: 6721bf02a3b4c5d6e7f8a9b0 organizationId: 66a0f1e2d3c4b5a697887766 feature: company_enrichment creditsUtilized: 2 sourceService: agent description: Company enrichment metadata: {} meta: organizationId: 66a0f1e2d3c4b5a697887766 feature: company_enrichment sourceService: agent createdAt: '2026-11-04T09:58:11.000Z' '400': description: Validation failed content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '401': description: Unauthenticated content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '404': description: Not found content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' '429': description: Rate limited content: application/json: schema: $ref: '#/components/schemas/ErrorEnvelope' components: schemas: OffsetPagination: type: object description: >- Page-number paging, used when you send `page` (or `offset`), a non-default sort, or grouping. Which keys are present depends on the endpoint; each endpoint's description lists them. additionalProperties: true properties: page: type: integer description: The page returned, starting at 1. limit: type: integer description: Rows per page. pageSize: type: integer description: Rows per page, on endpoints that call it pageSize. offset: type: integer description: Rows skipped, on endpoints that page by offset. total: type: integer description: Total matching rows, when the endpoint counts them. count: type: integer description: Total matching rows, on endpoints that call it count. totalPages: type: integer description: Number of pages at this page size. hasMore: type: boolean description: Whether another page exists. UsageEntry: type: object description: >- One credit charge. Entries are written by Heliyos when a feature spends credits; you cannot create or change them. properties: _id: $ref: '#/components/schemas/ObjectId' organizationId: allOf: - $ref: '#/components/schemas/ObjectId' description: The workspace that was charged. feature: type: string description: > What spent the credits. Values written today: - `worker_run`: a custom worker called during a run (default workers are free). - `company_enrichment`: a company was enriched. - `people_enrichment`: people were enriched for a lead set. - `leadset_enrichment`: lead set columns were enriched. - `leadset_match`: a lead set search and match. - `ai_column`: AI column research on records. - `scout`: a Scout run. - `meeting_analysis`: a meeting recording was analysed. - `agent_operation`: a generic charge with no more specific feature. Older entries can carry other names. Treat the field as an open set. example: worker_run creditsUtilized: type: number minimum: 0 exclusiveMinimum: true description: Credits spent by this entry. Always greater than 0. example: 5 objectId: type: string description: >- Id of what the credits were spent on, when there is one: a record id, or a run id for `worker_run`. Free text, not always a 24-character id. objectType: type: string description: >- The kind of thing `objectId` names, for example `orchestrator_run` for a worker run. Often absent. sourceService: type: string enum: - platform - agent - other description: Which part of Heliyos recorded the charge. description: type: string description: A short human-readable note about the charge. metadata: type: object additionalProperties: true description: >- Extra detail about the charge. For `worker_run`, `workerId` and `tool` name the worker that was called. meta: type: object additionalProperties: true description: >- An index copy of `organizationId`, `feature` and `sourceService`. Carries nothing the entry does not already have. createdAt: $ref: '#/components/schemas/Timestamp' ErrorEnvelope: type: object required: - message - error properties: message: type: string description: Same as error.message. error: type: object required: - code - message properties: code: type: string enum: - VALIDATION_FAILED - UNAUTHENTICATED - FORBIDDEN_ACTION - NOT_FOUND - RATE_LIMITED - CONFLICT - INTERNAL message: type: string details: {} ObjectId: type: string pattern: ^[0-9a-fA-F]{24}$ description: A 24-character hexadecimal id. example: 66f1a8c3e4b0a1b2c3d4e5f6 Timestamp: type: string format: date-time description: An ISO 8601 date-time in UTC. example: '2026-11-04T09:30:00.000Z' securitySchemes: bearerAuth: type: http scheme: bearer description: >- A workspace API key, sent as `Authorization: Bearer heliyos_...`. Create one in Heliyos under Settings → API keys. A key acts as a workspace admin in the one workspace it was created in. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.