> ## Documentation Index > Fetch the complete documentation index at: https://docs.hocdoc.com/llms.txt > Use this file to discover all available pages before exploring further. # List the events of an offer > The timeline of the offer, oldest first (by `sequence`). Use `next_cursor` to page. ## OpenAPI ````yaml /api-reference/openapi.json get /offers/{id}/events openapi: 3.1.0 info: title: HocDoc API version: 1.0.0 description: >- Read-only API for offers and their timeline. Send an API key as `Authorization: Bearer `. A key belongs to one workspace and only reads its data. Create keys in the app under Einstellungen, Integrationen. Timestamps are ISO 8601 in UTC with milliseconds. Values outside the years 0001 to 9999 are clamped to that range. Limits: 120 requests per minute per key and 300 requests per minute per IP address. See the `RateLimit-*` headers of each response. Compatibility: new fields, endpoints and event types may be added at any time, so ignore what you do not know. Breaking changes come under a new path (`/api/v2`). servers: - url: https://app.hocdoc.com/api/v1 description: Production security: - bearerAuth: [] tags: - name: Workspace description: The workspace of the API key. - name: Offers description: Offers and their timeline. paths: /offers/{id}/events: get: tags: - Offers summary: List the events of an offer description: >- The timeline of the offer, oldest first (by `sequence`). Use `next_cursor` to page. operationId: listOfferEvents parameters: - name: id in: path required: true description: ID of the offer. schema: type: string format: uuid - name: limit in: query required: false description: Page size, 1 to 200. schema: default: 50 type: integer minimum: 1 maximum: 200 - name: cursor in: query required: false description: Opaque cursor from `next_cursor` of the previous page. schema: type: string minLength: 1 maxLength: 512 responses: '200': description: A page of events. headers: RateLimit-Limit: description: Requests allowed per window for this API key. required: true schema: type: integer RateLimit-Remaining: description: Requests left in the current window. required: true schema: type: integer RateLimit-Reset: description: Seconds until the current window ends. required: true schema: type: integer content: application/json: schema: $ref: '#/components/schemas/OfferEventListResponse' examples: accepted_offer: summary: Timeline of an accepted offer value: data: - sequence: 1 type: created occurred_at: '2026-09-28T09:00:12.481Z' version: null data: {} - sequence: 2 type: sent occurred_at: '2026-09-29T10:15:00.642Z' version: 1 data: recipient_email: john@example.com - sequence: 3 type: viewed occurred_at: '2026-09-29T11:02:11.480Z' version: 1 data: {} - sequence: 4 type: section_viewed occurred_at: '2026-09-29T11:02:40.112Z' version: 1 data: section_id: pricing-1 duration_ms: 4200 - sequence: 5 type: code_requested occurred_at: '2026-10-02T14:06:58.320Z' version: 1 data: signer_email: john@example.com - sequence: 6 type: code_verified occurred_at: '2026-10-02T14:07:31.775Z' version: 1 data: signer_email: john@example.com - sequence: 7 type: accepted occurred_at: '2026-10-02T14:07:45.912Z' version: 1 data: signer_email: john@example.com next_cursor: null expired_offer: summary: Timeline of an expired offer value: data: - sequence: 1 type: created occurred_at: '2026-09-01T07:30:00.000Z' version: null data: {} - sequence: 2 type: sent occurred_at: '2026-09-02T08:00:11.205Z' version: 1 data: recipient_email: alex@example.com - sequence: 3 type: expired occurred_at: '2026-09-15T22:00:00.250Z' version: 1 data: expires_at: '2026-09-15T21:59:59.000Z' next_cursor: null '400': description: >- Invalid query parameter, or a query string longer than 1024 characters (`invalid_request`). headers: RateLimit-Limit: description: >- Requests allowed per window for this API key. Not sent when the query string is too long. required: false schema: type: integer RateLimit-Remaining: description: >- Requests left in the current window. Not sent when the query string is too long. required: false schema: type: integer RateLimit-Reset: description: >- Seconds until the current window ends. Not sent when the query string is too long. required: false schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalid_parameter: value: error: code: invalid_request message: Invalid value for query parameter "limit". param: limit query_too_long: value: error: code: invalid_request message: Query string too long. '401': description: >- Missing or invalid API key. The response is the same for a missing, malformed, unknown, revoked or expired key. headers: RateLimit-Limit: description: >- Requests allowed per window for this API key. Not sent when the key is missing or malformed. required: false schema: type: integer RateLimit-Remaining: description: >- Requests left in the current window. Not sent when the key is missing or malformed. required: false schema: type: integer RateLimit-Reset: description: >- Seconds until the current window ends. Not sent when the key is missing or malformed. required: false schema: type: integer WWW-Authenticate: description: The authentication scheme the API expects. Always `Bearer`. required: true schema: type: string examples: - Bearer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: unauthorized: value: error: code: unauthorized message: Missing or invalid API key. '404': description: >- Resource not found. The response is the same for an unknown ID, an ID of another workspace and an ID in the wrong form. headers: RateLimit-Limit: description: Requests allowed per window for this API key. required: true schema: type: integer RateLimit-Remaining: description: Requests left in the current window. required: true schema: type: integer RateLimit-Reset: description: Seconds until the current window ends. required: true schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: not_found: value: error: code: not_found message: Resource not found. '405': description: >- Method not allowed. This API is read-only. Sent for `POST`, `PUT`, `PATCH` and `DELETE` on this path. No API key is needed and the rate limit headers are not sent. headers: Allow: description: The methods this path accepts. required: true schema: type: string examples: - GET, HEAD, OPTIONS content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: method_not_allowed: value: error: code: method_not_allowed message: Method not allowed. This API is read-only. '429': description: >- Too many requests. Either the limit per API key or the limit per IP address was reached. headers: RateLimit-Limit: description: >- Requests allowed per window for this API key. Not sent when the limit per IP address was reached. required: false schema: type: integer RateLimit-Remaining: description: >- Requests left in the current window. Not sent when the limit per IP address was reached. required: false schema: type: integer RateLimit-Reset: description: >- Seconds until the current window ends. Not sent when the limit per IP address was reached. required: false schema: type: integer Retry-After: required: true description: Seconds to wait before the next request. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: rate_limited: value: error: code: rate_limited message: Too many requests. '500': description: Internal server error. headers: RateLimit-Limit: description: Requests allowed per window for this API key. required: true schema: type: integer RateLimit-Remaining: description: Requests left in the current window. required: true schema: type: integer RateLimit-Reset: description: Seconds until the current window ends. required: true schema: type: integer content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: internal_error: value: error: code: internal_error message: Internal server error. components: schemas: OfferEventListResponse: type: object properties: data: type: array items: $ref: '#/components/schemas/OfferEvent' description: The events of this page, oldest first. next_cursor: description: Pass as `cursor` to fetch the next page. Null on the last page. type: - string - 'null' required: - data - next_cursor description: A page of events of one offer. ErrorResponse: type: object properties: error: type: object properties: code: type: string enum: - unauthorized - not_found - invalid_request - method_not_allowed - rate_limited - internal_error description: Stable, machine-readable error code. message: type: string description: Human-readable message. May change, do not parse. param: description: The query parameter that was rejected. type: string required: - code - message required: - error description: Every error of the API has this shape. OfferEvent: type: object properties: sequence: type: integer minimum: 1 description: >- Position of the event in the timeline of its offer, starting at 1. Stable. type: type: string description: >- Event type. Known values: created, edited, sent, viewed, section_viewed, calculator_used, summary_viewed, code_requested, code_failed, code_verified, accepted, declined, expired, withdrawn. New types may be added, clients must ignore types they do not know. examples: - sent occurred_at: type: string format: date-time examples: - '2026-10-06T08:15:30.123Z' description: When the event happened. version: type: - integer - 'null' minimum: 1 description: Number of the offer version the event refers to, if any. data: $ref: '#/components/schemas/OfferEventData' required: - sequence - type - occurred_at - version - data description: One entry in the timeline of an offer. OfferEventData: type: object properties: recipient_email: description: Event `sent`. type: string section_id: description: Event `section_viewed`. type: string duration_ms: description: Event `section_viewed`. type: integer minimum: 0 expires_at: description: >- Event `expired`: the deadline that passed, truncated to whole seconds. It can differ from `expires_at` of the offer in the milliseconds. examples: - '2026-10-20T21:59:59.000Z' type: string format: date-time signer_email: description: Events `code_requested`, `code_failed`, `code_verified`, `accepted`. type: string description: >- Details of an event. Which fields are present depends on `type`. May be empty. securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key description: API key, for example `hd_live_…`. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.