> ## Documentation Index > Fetch the complete documentation index at: https://developers.hubspot.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Webhook journal APIs (2027-03-beta) > Learn how to use the latest version of the webhook journal APIs (2027-03-beta). > [!WARNING] > > This functionality is currently in beta. By participating in this beta, you agree to HubSpot's [Developer Terms](https://legal.hubspot.com/developer-terms) and [Developer Beta Terms](https://legal.hubspot.com/developerbetaterms). Note that the functionality is still under active development and is subject to change based on testing and feedback. The journal API endpoints provide access to historical event data stored in chronological order, allowing you to query for changes that occurred for your subscriptions over the past 3 days. These endpoints are optimized for performant access to object and property change data, especially compared to alternatives like the [CRM search API](https://developers.hubspot.com/docs/api-reference/latest/crm/search-the-crm.md). ## Before you get started You'll need to generate a client credentials token to use the webhook journals API. More information on how to generate this token is available in the authentication section of [overview](https://developers.hubspot.com/docs/api-reference/2027-03-beta/webhooks-journal/guide.md#authentication-and-scopes) article. ## Retrieve journal data The journal API has two variants: * **Global journal** (`/webhooks-journal/journal/2027-03-beta/...`): returns events across all accounts where the app is installed. * **Local journal** (`/webhooks-journal/journal-local/2027-03-beta/...`): returns events scoped to a specific account where the app is installed, identified by the optional `installPortalId` query parameter. The sections below outline out how to retrieve the earliest, latest, or next entry in the journal. * When using each of these endpoints, you'll need to ensure your [client credentials token](https://developers.hubspot.com/docs/api-reference/2027-03-beta/webhooks-journal/guide.md#authentication-and-scopes) was generated with the `developer.webhooks_journal.read` scope specified. * A successful response will include a `url` property, which you can then use to retrieve the file for the associated journal data. ### Get earliest journal entry To retrieve the earliest available journal entry for your app, make a `GET` request to `/webhooks-journal/journal/2027-03-beta/earliest`. The response will resemble the following: ```json theme={null} { "url": "https://s3.amazonaws.com/bucket/path/to/journal/file.json", "expiresAt": "2024-01-01T12:00:00Z", "currentOffset": "550e8400-e29b-41d4-a716-446655440000" } ``` ### Get latest journal entry To retrieve the latest available journal entry for your app, make a `GET` request to `/webhooks-journal/journal/2027-03-beta/latest`. The response will resemble the following: ```json theme={null} { "url": "https://s3.amazonaws.com/bucket/path/to/journal/file.json", "expiresAt": "2024-01-01T12:00:00Z", "currentOffset": "550e8400-e29b-41d4-a716-446655440000" } ``` ### Get next journal entry To retrieve the next journal entry after a specific offset, make a `GET` request to `/webhooks-journal/journal/2027-03-beta/offset/{offset}/next`. The `offset` path parameter is the UUID offset from the previous journal entry. For example, using the response from the previous sections, you'd make a `GET` request to `/webhooks-journal/journal/2027-03-beta/offset/550e8400-e29b-41d4-a716-446655440000/next`. ```json theme={null} { "url": "https://s3.amazonaws.com/bucket/path/to/journal/file.json", "expiresAt": "2024-01-01T12:00:00Z", "currentOffset": "550e8400-e29b-41d4-a716-446655440000" } ``` ## Batch journal operations Use batch operations for efficient retrieval of multiple journal entries in a single request, which improves throughput for high-volume data processing. All batch endpoints are exempt from the standard daily and per-second API [rate limits](https://developers.hubspot.com/docs/developer-tooling/platform/usage-guidelines.md#rate-limits), but are still subject to the [journal-specific rate limits](#rate-limits) detailed at the bottom of this article. When using each of the batch endpoints, you'll need to ensure your [client credentials token](https://developers.hubspot.com/docs/api-reference/2027-03-beta/webhooks-journal/guide.md#authentication-and-scopes) was generated with the `developer.webhooks_journal.read` scope specified. ### Batch retrieve by offset To retrieve multiple journal entries by offset UUID, make a `POST` request to `/webhooks-journal/journal-local/2027-03-beta/batch/read`. In the request body, provide the list of offset UUIDs within the `inputs` array. The code block below provides an example JSON payload to include in your request body, along with an example `cURL` request to retrieve journal entries using three offset UUIDs: ```json JSON theme={null} { "inputs": [ "550e8400-e29b-41d4-a716-446655440000", "7c9e6679-7425-40de-944b-e07fc1f90ae7", "a3bb189e-8bf9-3888-9912-ace4e6543002" ] } ``` ```bash cURL theme={null} curl -X POST \ https://api.hubapi.com/webhooks-journal/journal-local/2027-03-beta/batch/read \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "inputs": [ "550e8400-e29b-41d4-a716-446655440000", "7c9e6679-7425-40de-944b-e07fc1f90ae7", "a3bb189e-8bf9-3888-9912-ace4e6543002" ] }' ``` ### Batch retrieve earliest entries To retrieve the earliest entries in the journal for your app, make a `GET` request to `/webhooks-journal/journal-local/2027-03-beta/batch/earliest/{count}`. This is useful for an initial backfill or replaying from the beginning of the journal. You can also provide an optional `installPortalId` query parameter to filter results to a specific HubSpot account. For example, to retrieve the five earliest entries in the journal, you could make the following `cURL` request: ```bash theme={null} curl -X GET \ "https://api.hubapi.com/webhooks-journal/journal-local/2027-03-beta/batch/earliest/5" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Batch retrieve latest entries To retrieve the latest entries in the journal, make a `GET` request to `/webhooks-journal/journal-local/2027-03-beta/batch/latest/{count}`. This can be useful for catching up after a gap in your data, or checking the most recent activity for your subscriptions. You can also provide an optional `installPortalId` query parameter to filter results to a specific HubSpot account. For example, to retrieve the five most recent entries in the journal, you could make the following `cURL` request: ```bash theme={null} curl -X GET \ "https://api.hubapi.com/webhooks-journal/journal-local/2027-03-beta/batch/latest/5" \ -H "Authorization: Bearer YOUR_ACCESS_TOKEN" ``` ### Batch endpoint response format All batch endpoints return the same response format that includes the following properties: | Property | Type | Description | | - | - | - | | `status` | String | The state of the request. | | `startedAt` | String | An ISO 8601 formatted timestamp denoting the time the request was initiated. | | `completedAt` | String | An ISO 8601 formatted timestamp denoting the time the request was completed. | | `results` | Array | A list of journal entries that match the parameters provided in the request. | | `numErrors` | Number | The number of errors that occurred while processing the request. | | `errors` | Array | A list of the detailed errors that occurred while processing the request. | The code block below provides an example successful response with a single journal entry returned: ```json theme={null} { "status": "COMPLETE", "startedAt": "2024-01-01T12:00:00.000Z", "completedAt": "2024-01-01T12:00:00.123Z", "results": [ { "url": "https://s3.amazonaws.com/bucket/path/to/journal.json", "expiresAt": "2024-01-01T13:00:00.000Z", "currentOffset": "550e8400-e29b-41d4-a716-446655440000" } ], "numErrors": 0, "errors": [] } ``` If one or more entries failed to be returned, they'll appear in the `errors` array. The failed offset UUID is located within `context.offset[0]` of each error element. An example internal error is shown below: ```json theme={null} { "status": "error", "category": "INTERNAL_SERVER_ERROR", "message": "An internal error occurred while processing this journal entry. Please try again later.", "context": { "offset": ["a3bb189e-8bf9-3888-9912-ace4e6543002"] }, "errors": [], "links": {} } ``` Common error statuses you might encounter are detailed in the table below: | Status | Description | | - | - | | `NOT_FOUND` | No journal entry exists for the given offset. | | `PRESIGNING_ERROR` | The entry exists but a signed URL could not be generated. Retrying the offset may succeed. | | `VALIDATION_ERROR` | Batch size exceeds the maximum allowed limit of 100 entries. | ### Get journal status To retrieve the status of a journal snapshot operation, make a `GET` request to `/webhooks-journal/journal/2027-03-beta/status/{statusId}`, where `statusId` is the UUID returned when a snapshot was requested. ### Local journal The local journal endpoints follow the same pattern as the global journal, but are scoped to a specific account. Use the `installPortalId` query parameter to specify the account. * `GET /webhooks-journal/journal-local/2027-03-beta/earliest` * `GET /webhooks-journal/journal-local/2027-03-beta/latest` * `GET /webhooks-journal/journal-local/2027-03-beta/offset/{offset}/next` * `GET /webhooks-journal/journal-local/2027-03-beta/status/{statusId}` ## Rate limits The journal API endpoints are subject to a limit of 100 requests per second per app. Learn more about the related rate limits for the management APIs [here](https://developers.hubspot.com/docs/api-reference/2027-03-beta/webhooks-journal/subscriptions/guide.md#rate-limits).