> ## Documentation Index > Fetch the complete documentation index at: https://docs.watchdog.no/llms.txt > Use this file to discover all available pages before exploring further. # Read an entity activity timeline > Returns individual events and top-level comments, newest first. Supports invoices, agreements, individual alerts, claims, and topics (events only). Related-alert inclusion is explicit and adds events only. Alert filters match direct identities and recorded alert references before pagination; they return events only. Cursors retain timestamp precision and bind to the organization, entity and filters. Optional group_changes returns grouping metadata for this page only, using a rolling five-minute window. Comments break groups. value_blind_actions ignores change values for selected actions on the same entity. Pagination always counts entries, including when groups span pages. This is a live feed, not a snapshot or version-history API. ## OpenAPI ````yaml /openapi-preview.json get /v1/activity openapi: 3.1.0 info: title: Watchdog API (preview) version: 1.0.0 description: >- Development preview for agreements, price items, document relationships, canonical invoices, alerts and alert topics, claims and attached alerts, shared entity activity and comments, Document uploads, invoice imports, explicit invoice-agreement matching, and workflow runs. This contract is under development and is not served by api.watchdog.no. Request bodies are limited to 2 MiB (2,097,152 bytes), including all JSON fields and line data, except POST /v1/support/contact which permits 32 MiB for base64 attachments. File bytes are uploaded directly to storage. The existing public REST service retains its separate contract. servers: - url: http://localhost:3500 description: Local development Worker security: [] paths: /v1/activity: get: tags: - Activity summary: Read an entity activity timeline description: >- Returns individual events and top-level comments, newest first. Supports invoices, agreements, individual alerts, claims, and topics (events only). Related-alert inclusion is explicit and adds events only. Alert filters match direct identities and recorded alert references before pagination; they return events only. Cursors retain timestamp precision and bind to the organization, entity and filters. Optional group_changes returns grouping metadata for this page only, using a rolling five-minute window. Comments break groups. value_blind_actions ignores change values for selected actions on the same entity. Pagination always counts entries, including when groups span pages. This is a live feed, not a snapshot or version-history API. operationId: listActivity parameters: - name: X-Organization-Id in: header required: false schema: type: string description: >- Required for personal API keys. Target one organization you have access to. Migrated keys may omit it to use their original organization. For Clerk sessions, it must match the active organization. - schema: type: integer minimum: 1 maximum: 100 default: 50 description: Maximum number of results per page. required: false description: Maximum number of results per page. name: limit in: query - schema: type: string maxLength: 4096 description: >- Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page. required: false description: >- Opaque next_cursor from the previous page. Keep the same filters and sort; omit for the first page. name: cursor in: query - schema: type: string enum: - agreement - invoice - alert - claim - topic - invoice_import - document required: true name: entity_type in: query - schema: type: string format: uuid required: true name: entity_id in: query - schema: type: string enum: - activity - comment required: false name: entry_type in: query - schema: type: string enum: - 'true' - 'false' default: 'false' required: false name: include_related_alerts in: query - schema: type: string enum: - 'true' - 'false' default: 'false' description: >- Include page-local grouping metadata. Pagination still counts entries, not groups. required: false description: >- Include page-local grouping metadata. Pagination still counts entries, not groups. name: group_changes in: query - schema: type: string description: >- Actions grouped by changed field names rather than values. Requires group_changes=true; at most 50 actions. required: false description: >- Actions grouped by changed field names rather than values. Requires group_changes=true; at most 50 actions. name: value_blind_actions in: query - schema: type: string enum: - 'true' - 'false' description: >- Override automatic suppression of redundant alert summaries. Omit to suppress only when related alerts contribute events. required: false description: >- Override automatic suppression of redundant alert summaries. Omit to suppress only when related alerts contribute events. name: suppress_alert_scope_rollups in: query - schema: type: string format: uuid required: false name: alert_id in: query - schema: type: string enum: - is - is_not default: is required: false name: alert_operator in: query responses: '200': description: A page of timeline entries and an opaque next cursor. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: type: object properties: data: type: array items: $ref: '#/components/schemas/TimelineEntry' maxItems: 100 next_cursor: type: - string - 'null' groups: type: array items: type: object properties: key: type: string description: >- Grouping signature. Adjacent fragments with this key may join only within the rolling five-minute window, without an intervening comment. event_ids: type: array items: type: string format: uuid minItems: 1 maxItems: 100 first_occurred_at: type: string format: date-time last_occurred_at: type: string format: date-time required: - key - event_ids - first_occurred_at - last_occurred_at maxItems: 100 required: - data - next_cursor '400': description: >- Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes). headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_validation_error' example: error: code: validation_error message: >- Invalid request format, parameters, or body. Details contain up to 20 actionable field errors; the complete encoded request body must be at most 2 MiB (2,097,152 bytes). request_id: req_example '401': description: Missing or invalid bearer credential. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. WWW-Authenticate: schema: type: string required: false description: Bearer authentication challenge, when supplied. content: application/json: schema: $ref: '#/components/schemas/Error_invalid_token' example: error: code: invalid_token message: Missing or invalid bearer credential. request_id: req_example '403': description: >- Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: >- #/components/schemas/Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required example: error: code: forbidden message: >- Access denied: forbidden, token_disabled, organization_required, insufficient_role, or mfa_required. Check the error code and effective permissions. request_id: req_example '404': description: The resource does not exist in the current organization. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_not_found' example: error: code: not_found message: The resource does not exist in the current organization. request_id: req_example '429': description: The IP or authenticated credential exceeded its request limit. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. Retry-After: schema: type: string example: '60' required: true description: Seconds to wait before retrying the request. content: application/json: schema: $ref: '#/components/schemas/Error_rate_limit_exceeded' example: error: code: rate_limit_exceeded message: >- The IP or authenticated credential exceeded its request limit. request_id: req_example '500': description: >- Unexpected server failure. Include the request ID when contacting support. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. content: application/json: schema: $ref: '#/components/schemas/Error_internal_error' example: error: code: internal_error message: >- Unexpected server failure. Include the request ID when contacting support. request_id: req_example '503': description: >- Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided. headers: X-Request-Id: schema: type: string required: true description: >- Request identifier for support and diagnostics; also included in error bodies. Cache-Control: schema: type: string enum: - private, no-store required: false description: >- Organization-scoped API responses must not be cached. May be absent for requests rejected before routing. X-RateLimit-Limit: schema: type: string example: '120' required: false description: >- Requests per minute for the applicable limiter, when evaluated. Authenticated requests use the credential limit; an IP rejection uses the IP limit. Retry-After: schema: type: string example: '60' required: true description: Seconds to wait before retrying the request. content: application/json: schema: $ref: '#/components/schemas/Error_service_unavailable' example: error: code: service_unavailable message: >- Authentication infrastructure is unavailable or rate limited. Honor Retry-After when provided. request_id: req_example security: - ApiKeyBearer: [] - ClerkSessionBearer: [] components: schemas: TimelineEntry: oneOf: - $ref: '#/components/schemas/Activity' - $ref: '#/components/schemas/Comment' discriminator: propertyName: type mapping: activity: $ref: '#/components/schemas/Activity' comment: $ref: '#/components/schemas/Comment' Error_validation_error: type: object properties: error: type: object properties: code: type: string enum: - validation_error message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_invalid_token: type: object properties: error: type: object properties: code: type: string enum: - invalid_token message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_forbidden_token_disabled_organization_required_insufficient_role_mfa_required: type: object properties: error: type: object properties: code: type: string enum: - forbidden - token_disabled - organization_required - insufficient_role - mfa_required message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_not_found: type: object properties: error: type: object properties: code: type: string enum: - not_found message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_rate_limit_exceeded: type: object properties: error: type: object properties: code: type: string enum: - rate_limit_exceeded message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_internal_error: type: object properties: error: type: object properties: code: type: string enum: - internal_error message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Error_service_unavailable: type: object properties: error: type: object properties: code: type: string enum: - service_unavailable message: type: string request_id: type: string description: type: string details: type: array items: type: object properties: code: type: string field: type: string message: type: string required: - code - field - message maxItems: 20 workflow_run_id: type: string format: uuid import_id: type: string format: uuid existing_party: type: object properties: type: type: string enum: - supplier - recipient id: type: string format: uuid required: - type - id required: - code - message - request_id required: - error Activity: type: object properties: type: type: string enum: - activity id: type: string format: uuid entity_type: type: string enum: - agreement - invoice - alert - claim - topic - invoice_import - document entity_id: type: string format: uuid occurred_at: type: string format: date-time action: type: string description: >- Extensible domain action identifier. Consumers must accept unknown actions. actor: type: object properties: type: type: string enum: - user - system - integration user_id: type: - string - 'null' source: type: - string - 'null' label: type: - string - 'null' required: - type - user_id - source - label detail: $ref: '#/components/schemas/ActivityDetailV1' entity_version: type: - integer - 'null' required: - type - id - entity_type - entity_id - occurred_at - action - actor - detail - entity_version Comment: type: object properties: type: type: string enum: - comment id: type: string format: uuid entity_type: type: string enum: - invoice - agreement - alert - claim entity_id: type: string format: uuid parent_comment_id: type: - string - 'null' format: uuid body: type: string author: type: object properties: user_id: type: - string - 'null' name: type: - string - 'null' required: - user_id - name occurred_at: type: string format: date-time created_at: type: string format: date-time updated_at: type: string format: date-time reply_count: type: integer minimum: 0 required: - type - id - entity_type - entity_id - parent_comment_id - body - author - occurred_at - created_at - updated_at - reply_count ActivityDetailV1: type: - object - 'null' properties: schemaVersion: type: number enum: - 1 changes: type: array items: type: object properties: field: type: string from: $ref: '#/components/schemas/ActivityValue' to: $ref: '#/components/schemas/ActivityValue' required: - field - from - to additionalProperties: $ref: '#/components/schemas/ActivityValue' data: type: object additionalProperties: $ref: '#/components/schemas/ActivityValue' operation: type: string summary: type: object additionalProperties: $ref: '#/components/schemas/ActivityValue' required: - schemaVersion additionalProperties: false ActivityValue: type: - string - number - boolean - 'null' - array - object items: $ref: '#/components/schemas/ActivityValue' additionalProperties: $ref: '#/components/schemas/ActivityValue' securitySchemes: ApiKeyBearer: type: http scheme: bearer description: >- Personal API key. Send X-Organization-Id. The required cumulative level is listed in x-watchdog-permission. ClerkSessionBearer: type: http scheme: bearer description: Clerk session with an active organization. ````