> ## 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.

# History Exports

> Export usage and query history across your organization

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.

<Note>
  The current API request rate limits for History Export API endpoints are **60 requests per minute**.
</Note>

```bash theme={null}
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

<Note>
  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.
</Note>

<Warning>
  The **v2** history APIs are not yet generally available. GA is planned for **March 25, 2026**. Please reach out to your Harvey Customer Success Manager if you have questions about early access.
</Warning>

<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.
</Warning>

### 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

```bash theme={null}
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.

```bash theme={null}
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:**

```json theme={null}
{
  "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

```bash theme={null}
GET /api/v1/history/usage
```

Returns a flat array of usage events with basic metadata.

```bash theme={null}
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

```bash theme={null}
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.

```bash theme={null}
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:**

```json theme={null}
{
  "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

```bash theme={null}
GET /api/v1/history/query
```

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

```bash theme={null}
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.