> ## Documentation Index
> Fetch the complete documentation index at: https://developers.harvey.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Usage History (v2)

> Fetches the usage history and metadata for a specified time range. Returns enriched event data with product surface area, subsurface details, and additional metadata across Harvey product areas.

> **Warning:** These APIs include sensitive data for resource names across your entire workspace, and are not gated by any form of client-matter or ethical wall boundaries. We recommend caution when pulling this information via API and sharing API tokens carefully and selectively.


### Permissions

Requires `Territory admin` or `Organization admin`, and `View history` permissions.


## OpenAPI

````yaml /history_export_api.json get /api/v2/history/usage
openapi: 3.0.1
info:
  title: v2 - Harvey History Export API
  description: >
    The Harvey API enables customers to fetch query and workspace history for
    their workspace. This includes query events and usage history with relevant
    metadata.
  version: 2.0.0
  contact:
    email: support@harvey.ai
servers:
  - url: https://api.harvey.ai
    description: Harvey API server
security: []
paths:
  /api/v2/history/usage:
    get:
      tags:
        - Usage
      summary: Get Usage History (v2)
      description: >
        Fetches the usage history and metadata for a specified time range.
        Returns enriched event data with product surface area, subsurface
        details, and additional metadata across Harvey product areas.


        > **Warning:** These APIs include sensitive data for resource names
        across your entire workspace, and are not gated by any form of
        client-matter or ethical wall boundaries. We recommend caution when
        pulling this information via API and sharing API tokens carefully and
        selectively.
      operationId: getUsageHistoryV2
      parameters:
        - name: start_time
          in: query
          required: true
          schema:
            type: integer
            format: date-time
            description: UTC epoch timestamp, up to 1 year ago from now
        - name: end_time
          in: query
          required: true
          schema:
            type: integer
            format: date-time
            description: >-
              UTC epoch timestamp, up to 30 days from start_time. Note: The API
              supports a maximum range of 30 days, but it's best to retrieve a
              max of one day at a time on a regular cadence.
        - name: include_file_ids
          in: query
          required: false
          schema:
            type: boolean
            default: false
            description: >-
              When set to true, the response will include file_ids for each
              event. This may impact performance, so only enable when needed
              (e.g., to use with the file download endpoint).
      responses:
        '200':
          description: Object containing an array of V2UsageHistory events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/V2UsageHistoryResponse'
        '400':
          description: Bad request.
        '401':
          description: Unauthorized.
        '429':
          description: Rate limit exceeded.
        '500':
          description: Internal server error.
      security:
        - bearerAuth: []
components:
  schemas:
    V2UsageHistoryResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/V2UsageHistory'
          description: Array of usage history events.
    V2UsageHistory:
      type: object
      properties:
        access_point:
          type: string
          description: The access point from which the event was triggered.
          example: WEB
        action:
          type: string
          description: The type of action performed.
          example: CREATE
        cm_id:
          type: string
          description: Client matter number associated with the event, if any.
          example: '1234.56'
        file_ids:
          type: array
          items:
            type: string
            format: uuid
          description: >-
            Array of file IDs associated with the event. Only included when the
            include_file_ids query parameter is set to true.
          example:
            - 019d35f0-4cf5-7296-aef5-45991d83a77b
            - 019d35f0-4cf1-7f4f-a09b-885f9066638e
        parent_thread_id:
          type: integer
          description: >-
            Parent Thread ID indicates the original started thread, and can
            appear more than once (e.g., if someone asks a follow-up in a thread
            three times, it will appear those three times).
          example: 2374992
        playbook_name:
          type: string
          description: Name of the playbook used, if any.
          example: ''
        product_surface_area:
          type: string
          description: The Harvey product area(s) where the event occurred.
          example: ASSISTANT
        review_table_name:
          type: string
          description: Name of the Vault review table, if applicable.
          example: Supply Agreement Details and Key Terms
        source:
          type: string
          description: Source(s) of the documents or data used in the event.
          example: Files
        space_name:
          type: string
          description: Name of the space associated with the event, if any.
          example: ''
        subsurface:
          type: string
          description: >-
            The specific subsurface(s) or feature(s) within the product surface
            area.
          example: ASSISTANT_THREAD, ASSISTANT_THREAD_FOLLOWUP
        utc_time:
          type: string
          description: Timestamp of the event in UTC.
          example: '2026-02-22 14:01:23'
        unique_usage_id:
          type: string
          format: uuid
          description: Unique identifier for the usage event.
          example: 019c85a7-a7c9-784f-bc59-0ddd5654274d
        user:
          type: string
          description: Email of the user who triggered the event.
          example: user@example.com
        vault_project_name:
          type: string
          description: Name of the Vault project, if applicable.
          example: 48CommercialContracts
        workflow_name:
          type: string
          description: Name of the workflow used, if any.
          example: ''
        metadata:
          type: object
          additionalProperties: true
          description: >-
            Additional context specific to the product surface area and
            subsurface of the event. The keys and values vary depending on the
            event type. For example, a VAULT / REVIEW_TABLE event will include
            `num_columns` and `num_files`.
          example:
            num_columns: 5
            num_files: 48
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````