History Exports

Harvey’s History Export APIs let you retrieve detailed logs of how users are interacting with the platform. Use them to power usage reports, perform compliance investigations, or attribute activity to clients and matters.

The current API request rate limits for History Export API endpoints are 2 requests per minute.

GET /api/v2/history/usage
GET /api/v2/history/query
GET /api/v1/history/usage
GET /api/v1/history/query

Overview

The History APIs support:

Usage Tracking: Understand frequency, volume, and system-wide adoption
Query Forensics: Review exact prompts, outputs, and sources for internal audits or client escalations
Billing & Cost Attribution: Map usage and queries back to client-matter structures

The v2 endpoints return enriched event data with additional metadata such as product_surface_area, subsurface, vault_project_name, and more. We recommend using v2 for all new integrations.

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.

What’s new in v2

Workflow, playbook, and vault names to identify commonly used resources
Unique usage id (uuid) for every single usage log returned by the API
Clear distinction between creation vs. run for playbooks and workflows
Clear distinction between starting new threads vs. asking follow-up queries

Event Types

Each v2 history event includes a product_surface_area and subsurface field that identify where and how the event occurred. Below is a complete list of possible values.

Product Surface Area

Value	Description
`ASSISTANT`	Assistant product area
`VAULT`	Vault product area
`PLAYBOOK`	Playbook product area
`WORKFLOW`	Workflow product area
`WORD`	Word add-in
`OUTLOOK`	Outlook add-in
`DRAFT`	Draft product area

Subsurface

Value	Description
`ASSISTANT_THREAD`	A new Assistant thread was started
`ASSISTANT_THREAD_FOLLOWUP`	A follow-up message in an existing Assistant thread
`REVIEW_TABLE`	A Vault review table query was created/run
`WORKFLOW_PUBLISHED`	A published workflow was run
`WORKFLOW_TEST`	A workflow was run in test mode

Usage History

v2

GET /api/v2/history/usage

Returns usage events wrapped in an events array. Each event includes metadata about the product area, action type, and user — without sensitive inputs or outputs.

curl -X GET "https://api.harvey.ai/api/v2/history/usage?start_time=1711920000&end_time=1714521600" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "events": [
    {
      "access_point": "WEB",
      "action": "CREATE",
      "cm_id": "1234.56",
      "parent_thread_id": 2374992,
      "playbook_name": "",
      "product_surface_area": "ASSISTANT",
      "review_table_name": "",
      "source": "Files",
      "space_name": "",
      "subsurface": "ASSISTANT_THREAD, ASSISTANT_THREAD_FOLLOWUP",
      "utc_time": "2026-02-22 14:01:23",
      "unique_usage_id": "019c85a7-a7c9-784f-bc59-0ddd5654274d",
      "user": "user@example.com",
      "vault_project_name": "",
      "workflow_name": "",
      "metadata": {}
    }
  ]
}

v1

GET /api/v1/history/usage

Returns a flat array of usage events with basic metadata.

curl -X GET "https://api.harvey.ai/api/v1/history/usage?start_time=1711920000&end_time=1714521600" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use Cases

Usage Reporting and Oversight

Challenge: Firms need reliable, exportable usage metrics to support leadership reporting and billing. Solution: Pull usage data weekly or monthly and load it into your reporting environment. Use the product_surface_area field (v2) or Task field (v1) to break down usage by Harvey product.

Monitoring Adoption Across Teams

Challenge: Legal and operational leaders need to understand how teams are engaging with Harvey. Solution: Pull usage logs and associate them with user emails or internal department mappings. The v2 endpoint provides additional context through subsurface and access_point fields.

Query History

v2

GET /api/v2/history/query

Returns query events wrapped in an events array. Each event includes the full query and response text alongside all usage metadata.

curl -X GET "https://api.harvey.ai/api/v2/history/query?start_time=1711920000&end_time=1714521600" \
  -H "Authorization: Bearer YOUR_API_KEY"

Example response:

{
  "events": [
    {
      "access_point": "WEB",
      "action": "CREATE",
      "cm_id": "1234.56",
      "feedback_comments": "",
      "feedback_sentiments": "",
      "link": "https://app.harvey.ai/assistant/assist/2374992",
      "parent_thread_id": 2374992,
      "playbook_name": "",
      "product_surface_area": "ASSISTANT",
      "query": "Can you summarize the key indemnity provisions in this contract?",
      "response": "The contract contains three main indemnity provisions...",
      "review_table_name": "",
      "source": "Files",
      "space_name": "",
      "subsurface": "ASSISTANT_THREAD, ASSISTANT_THREAD_FOLLOWUP",
      "utc_time": "2026-02-22 14:01:23",
      "unique_usage_id": "019c85a7-a7c9-784f-bc59-0ddd5654274d",
      "user": "user@example.com",
      "vault_project_name": "",
      "workflow_name": "",
      "metadata": {}
    }
  ]
}

v1

GET /api/v1/history/query

Returns a flat array of query events including prompts, responses, and document references.

curl -X GET "https://api.harvey.ai/api/v1/history/query?start_time=1711920000&end_time=1714521600" \
  -H "Authorization: Bearer YOUR_API_KEY"

Use Cases

Deep Dive Analysis of Specific Queries

Challenge: Admins need to understand exactly what was asked, by whom, and what sources were used. Solution: Use query history logs to reconstruct an interaction. The v2 link field provides a direct URL to view the event in Harvey.

Reviewing Draft Quality and Sources

Challenge: Teams need to verify whether specific outputs were grounded in expected sources. Solution: Use the source and response fields (v2) to trace how the AI formulated its answer. In v1, the Documents field lists specific filenames used.

Best Practices

Limit to 1-day data pulls: 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.
Align client-matter attribution: Combine query and usage logs with client-matter metadata to analyze usage patterns and client activity. Use cm_id (v2) or Client Matter # (v1) to match events.
Analyze product usage: Use product_surface_area and subsurface (v2) or Task (v1) to understand how different Harvey features are used.
Trace user activity contextually: Use email, timestamp, and source fields to piece together how a user interacted with a specific document or feature.

Error Handling

Status Code	Description	Example Error Message
200, 201	Success	N/A
400	Bad Request – Missing or invalid input	`{ "error": "Missing start_time" }`
401	Unauthorized – Invalid API key	`{ "error": "Unauthorized" }`
429	Too Many Requests – Rate limit exceeded	`{ "error": "Rate limit exceeded" }`
500	Internal Server Error	`{ "error": "Unexpected server error" }`

Need help getting started? Contact your Harvey Customer Success Manager for more information.

Getting Started

Endpoint Overview

MCP (Beta)

History Exports

Overview

What’s new in v2

Event Types

Product Surface Area

Subsurface

Usage History

v2

v1

Use Cases

Usage Reporting and Oversight

Monitoring Adoption Across Teams

Query History

v2

v1

Use Cases

Deep Dive Analysis of Specific Queries

Reviewing Draft Quality and Sources

Best Practices

Error Handling

​Overview

​What’s new in v2

​Event Types

​Product Surface Area

​Subsurface

​Usage History

​v2

​v1

​Use Cases

​Usage Reporting and Oversight

​Monitoring Adoption Across Teams

​Query History

​v2

​v1

​Use Cases

​Deep Dive Analysis of Specific Queries

​Reviewing Draft Quality and Sources

​Best Practices

​Error Handling

Overview

What’s new in v2

Event Types

Product Surface Area

Subsurface

Usage History

v2

v1

Use Cases

Usage Reporting and Oversight

Monitoring Adoption Across Teams

Query History

v2

v1

Use Cases

Deep Dive Analysis of Specific Queries

Reviewing Draft Quality and Sources

Best Practices

Error Handling