> ## Documentation Index > Fetch the complete documentation index at: https://docs.cotool.ai/llms.txt > Use this file to discover all available pages before exploring further. # Get alert timeline > Retrieve paginated timeline entries for an alert. ## OpenAPI ````yaml https://app.cotool.ai/api/docs/openapi.json get /api/alerts/{alertId}/timeline openapi: 3.1.0 info: title: Cotool API version: 1.0.0 description: >- # Cotool API Documentation The Cotool API allows you to interact with the Cotool platform programmatically, enabling you to build powerful integrations and automate your workflows. ## Getting an API Key Follow these steps to generate your API key: 1. **Log in** to the Cotool web interface 2. **Navigate** to `/settings/api-keys` 3. **Click** "Generate Key" 4. **Copy and store** your API key securely ⚠️ *It won't be shown again* ## API Key Authentication For programmatic access and integrations, use your API key with the Authorization header: ```http Authorization: Bearer your_api_key_here ``` ```bash curl -X GET "https://app.cotool.ai/api/endpoint" \ -H "Authorization: Bearer your_api_key_here" \ -H "Content-Type: application/json" ``` servers: - url: https://app.cotool.ai description: Production server security: - ApiKeyAuth: [] paths: /api/alerts/{alertId}/timeline: get: tags: - Alerts summary: Get alert timeline description: Retrieve paginated timeline entries for an alert. parameters: - in: path name: alertId description: Alert UUID or human-readable display ID schema: type: string description: Alert UUID or human-readable display ID required: true - in: query name: limit description: Maximum number of timeline entries to return schema: type: integer minimum: 1 maximum: 200 default: 100 description: Maximum number of timeline entries to return - in: query name: offset description: Number of timeline entries to skip schema: type: integer minimum: 0 default: 0 description: Number of timeline entries to skip responses: '200': description: Successful response content: application/json: schema: type: object properties: entries: type: array items: oneOf: - type: object properties: id: type: string format: uuid description: Timeline entry identifier organizationId: type: string format: uuid description: Organization that owns the timeline entry alertId: type: string format: uuid description: Alert this entry belongs to createdAt: type: string description: ISO timestamp when the entry was created actorType: type: string enum: - human - agent - system description: Actor class responsible for a timeline entry. actorUserId: type: - string - 'null' format: uuid description: Human actor user id, when actorType is human actorAgentId: type: - string - 'null' format: uuid description: Agent actor id, when actorType is agent actorRunId: type: - string - 'null' format: uuid description: >- Run responsible for this entry, stored as chats.id actorUserName: type: - string - 'null' description: >- Resolved display name for a human actor, hydrated for rendering actorUserImageUrl: type: - string - 'null' description: >- Resolved avatar image URL for a human actor, when one is available actorAgentName: type: - string - 'null' description: >- Resolved display name for an agent actor or referenced assigned agent kind: type: string const: created bodyMarkdown: type: - string - 'null' description: Timeline body, when this entry has prose content beforeStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status before a status transition afterStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status after a status transition metadata: type: object properties: source: type: object properties: category: type: string enum: - detection - trigger - hunting description: >- Broad alert source category. Hunting is reserved for future threat-intel exposure alerts. name: type: string enum: - cotool_detection - hunting - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone description: >- Filter-oriented alert source name. Trigger-created alerts use the trigger type. triggerType: type: - string - 'null' enum: - jira - jira-automation - slack - linear - cron - webhook - email - bugcrowd - hackerone - null description: Trigger source when category is trigger required: - category - name - triggerType description: >- Filter-oriented source attribution for an alert. originDetectionHitId: type: - string - 'null' format: uuid originTriggerId: type: - string - 'null' format: uuid sourcePayloadId: type: string format: uuid additionalProperties: true description: Metadata for alert creation timeline entries. required: - id - organizationId - alertId - createdAt - actorType - actorUserId - actorAgentId - actorRunId - actorUserName - actorUserImageUrl - kind - bodyMarkdown - beforeStatus - afterStatus - metadata - type: object properties: id: type: string format: uuid description: Timeline entry identifier organizationId: type: string format: uuid description: Organization that owns the timeline entry alertId: type: string format: uuid description: Alert this entry belongs to createdAt: type: string description: ISO timestamp when the entry was created actorType: type: string enum: - human - agent - system description: Actor class responsible for a timeline entry. actorUserId: type: - string - 'null' format: uuid description: Human actor user id, when actorType is human actorAgentId: type: - string - 'null' format: uuid description: Agent actor id, when actorType is agent actorRunId: type: - string - 'null' format: uuid description: >- Run responsible for this entry, stored as chats.id actorUserName: type: - string - 'null' description: >- Resolved display name for a human actor, hydrated for rendering actorUserImageUrl: type: - string - 'null' description: >- Resolved avatar image URL for a human actor, when one is available actorAgentName: type: - string - 'null' description: >- Resolved display name for an agent actor or referenced assigned agent kind: type: string const: comment bodyMarkdown: type: - string - 'null' description: Timeline body, when this entry has prose content beforeStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status before a status transition afterStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status after a status transition metadata: type: object additionalProperties: true description: Metadata for alert comment timeline entries. required: - id - organizationId - alertId - createdAt - actorType - actorUserId - actorAgentId - actorRunId - actorUserName - actorUserImageUrl - kind - bodyMarkdown - beforeStatus - afterStatus - metadata - type: object properties: id: type: string format: uuid description: Timeline entry identifier organizationId: type: string format: uuid description: Organization that owns the timeline entry alertId: type: string format: uuid description: Alert this entry belongs to createdAt: type: string description: ISO timestamp when the entry was created actorType: type: string enum: - human - agent - system description: Actor class responsible for a timeline entry. actorUserId: type: - string - 'null' format: uuid description: Human actor user id, when actorType is human actorAgentId: type: - string - 'null' format: uuid description: Agent actor id, when actorType is agent actorRunId: type: - string - 'null' format: uuid description: >- Run responsible for this entry, stored as chats.id actorUserName: type: - string - 'null' description: >- Resolved display name for a human actor, hydrated for rendering actorUserImageUrl: type: - string - 'null' description: >- Resolved avatar image URL for a human actor, when one is available actorAgentName: type: - string - 'null' description: >- Resolved display name for an agent actor or referenced assigned agent kind: type: string const: status_change bodyMarkdown: type: - string - 'null' description: Timeline body, when this entry has prose content beforeStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status before a status transition afterStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status after a status transition metadata: type: object properties: reason: type: - string - 'null' agentId: type: string format: uuid runId: type: string format: uuid additionalProperties: true description: >- Metadata for alert status-change timeline entries. required: - id - organizationId - alertId - createdAt - actorType - actorUserId - actorAgentId - actorRunId - actorUserName - actorUserImageUrl - kind - bodyMarkdown - beforeStatus - afterStatus - metadata - type: object properties: id: type: string format: uuid description: Timeline entry identifier organizationId: type: string format: uuid description: Organization that owns the timeline entry alertId: type: string format: uuid description: Alert this entry belongs to createdAt: type: string description: ISO timestamp when the entry was created actorType: type: string enum: - human - agent - system description: Actor class responsible for a timeline entry. actorUserId: type: - string - 'null' format: uuid description: Human actor user id, when actorType is human actorAgentId: type: - string - 'null' format: uuid description: Agent actor id, when actorType is agent actorRunId: type: - string - 'null' format: uuid description: >- Run responsible for this entry, stored as chats.id actorUserName: type: - string - 'null' description: >- Resolved display name for a human actor, hydrated for rendering actorUserImageUrl: type: - string - 'null' description: >- Resolved avatar image URL for a human actor, when one is available actorAgentName: type: - string - 'null' description: >- Resolved display name for an agent actor or referenced assigned agent kind: type: string const: title_change bodyMarkdown: type: - string - 'null' description: Timeline body, when this entry has prose content beforeStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status before a status transition afterStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status after a status transition metadata: type: object properties: beforeTitle: type: - string - 'null' afterTitle: type: - string - 'null' additionalProperties: true description: >- Metadata for alert title-change timeline entries. required: - id - organizationId - alertId - createdAt - actorType - actorUserId - actorAgentId - actorRunId - actorUserName - actorUserImageUrl - kind - bodyMarkdown - beforeStatus - afterStatus - metadata - type: object properties: id: type: string format: uuid description: Timeline entry identifier organizationId: type: string format: uuid description: Organization that owns the timeline entry alertId: type: string format: uuid description: Alert this entry belongs to createdAt: type: string description: ISO timestamp when the entry was created actorType: type: string enum: - human - agent - system description: Actor class responsible for a timeline entry. actorUserId: type: - string - 'null' format: uuid description: Human actor user id, when actorType is human actorAgentId: type: - string - 'null' format: uuid description: Agent actor id, when actorType is agent actorRunId: type: - string - 'null' format: uuid description: >- Run responsible for this entry, stored as chats.id actorUserName: type: - string - 'null' description: >- Resolved display name for a human actor, hydrated for rendering actorUserImageUrl: type: - string - 'null' description: >- Resolved avatar image URL for a human actor, when one is available actorAgentName: type: - string - 'null' description: >- Resolved display name for an agent actor or referenced assigned agent kind: type: string const: description_change bodyMarkdown: type: - string - 'null' description: Timeline body, when this entry has prose content beforeStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status before a status transition afterStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status after a status transition metadata: type: object properties: beforeDescription: type: - string - 'null' afterDescription: type: - string - 'null' additionalProperties: true description: >- Metadata for alert description-change timeline entries. required: - id - organizationId - alertId - createdAt - actorType - actorUserId - actorAgentId - actorRunId - actorUserName - actorUserImageUrl - kind - bodyMarkdown - beforeStatus - afterStatus - metadata - type: object properties: id: type: string format: uuid description: Timeline entry identifier organizationId: type: string format: uuid description: Organization that owns the timeline entry alertId: type: string format: uuid description: Alert this entry belongs to createdAt: type: string description: ISO timestamp when the entry was created actorType: type: string enum: - human - agent - system description: Actor class responsible for a timeline entry. actorUserId: type: - string - 'null' format: uuid description: Human actor user id, when actorType is human actorAgentId: type: - string - 'null' format: uuid description: Agent actor id, when actorType is agent actorRunId: type: - string - 'null' format: uuid description: >- Run responsible for this entry, stored as chats.id actorUserName: type: - string - 'null' description: >- Resolved display name for a human actor, hydrated for rendering actorUserImageUrl: type: - string - 'null' description: >- Resolved avatar image URL for a human actor, when one is available actorAgentName: type: - string - 'null' description: >- Resolved display name for an agent actor or referenced assigned agent kind: type: string const: severity_change bodyMarkdown: type: - string - 'null' description: Timeline body, when this entry has prose content beforeStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status before a status transition afterStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status after a status transition metadata: type: object properties: beforeSeverity: type: - string - 'null' enum: - low - medium - high - critical - null afterSeverity: type: - string - 'null' enum: - low - medium - high - critical - null reason: type: - string - 'null' additionalProperties: true description: >- Metadata for alert severity-change timeline entries. required: - id - organizationId - alertId - createdAt - actorType - actorUserId - actorAgentId - actorRunId - actorUserName - actorUserImageUrl - kind - bodyMarkdown - beforeStatus - afterStatus - metadata - type: object properties: id: type: string format: uuid description: Timeline entry identifier organizationId: type: string format: uuid description: Organization that owns the timeline entry alertId: type: string format: uuid description: Alert this entry belongs to createdAt: type: string description: ISO timestamp when the entry was created actorType: type: string enum: - human - agent - system description: Actor class responsible for a timeline entry. actorUserId: type: - string - 'null' format: uuid description: Human actor user id, when actorType is human actorAgentId: type: - string - 'null' format: uuid description: Agent actor id, when actorType is agent actorRunId: type: - string - 'null' format: uuid description: >- Run responsible for this entry, stored as chats.id actorUserName: type: - string - 'null' description: >- Resolved display name for a human actor, hydrated for rendering actorUserImageUrl: type: - string - 'null' description: >- Resolved avatar image URL for a human actor, when one is available actorAgentName: type: - string - 'null' description: >- Resolved display name for an agent actor or referenced assigned agent kind: type: string const: assignment_change bodyMarkdown: type: - string - 'null' description: Timeline body, when this entry has prose content beforeStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status before a status transition afterStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status after a status transition metadata: type: object properties: reason: type: - string - 'null' assignedAgentId: type: - string - 'null' format: uuid runId: type: - string - 'null' format: uuid additionalProperties: true description: >- Metadata for alert assignment-change timeline entries. required: - id - organizationId - alertId - createdAt - actorType - actorUserId - actorAgentId - actorRunId - actorUserName - actorUserImageUrl - kind - bodyMarkdown - beforeStatus - afterStatus - metadata - type: object properties: id: type: string format: uuid description: Timeline entry identifier organizationId: type: string format: uuid description: Organization that owns the timeline entry alertId: type: string format: uuid description: Alert this entry belongs to createdAt: type: string description: ISO timestamp when the entry was created actorType: type: string enum: - human - agent - system description: Actor class responsible for a timeline entry. actorUserId: type: - string - 'null' format: uuid description: Human actor user id, when actorType is human actorAgentId: type: - string - 'null' format: uuid description: Agent actor id, when actorType is agent actorRunId: type: - string - 'null' format: uuid description: >- Run responsible for this entry, stored as chats.id actorUserName: type: - string - 'null' description: >- Resolved display name for a human actor, hydrated for rendering actorUserImageUrl: type: - string - 'null' description: >- Resolved avatar image URL for a human actor, when one is available actorAgentName: type: - string - 'null' description: >- Resolved display name for an agent actor or referenced assigned agent kind: type: string const: triage_run bodyMarkdown: type: - string - 'null' description: Timeline body, when this entry has prose content beforeStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status before a status transition afterStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status after a status transition metadata: type: object properties: reason: type: - string - 'null' agentId: type: string format: uuid runId: type: string format: uuid additionalProperties: true description: Metadata for alert triage-run timeline entries. required: - id - organizationId - alertId - createdAt - actorType - actorUserId - actorAgentId - actorRunId - actorUserName - actorUserImageUrl - kind - bodyMarkdown - beforeStatus - afterStatus - metadata - type: object properties: id: type: string format: uuid description: Timeline entry identifier organizationId: type: string format: uuid description: Organization that owns the timeline entry alertId: type: string format: uuid description: Alert this entry belongs to createdAt: type: string description: ISO timestamp when the entry was created actorType: type: string enum: - human - agent - system description: Actor class responsible for a timeline entry. actorUserId: type: - string - 'null' format: uuid description: Human actor user id, when actorType is human actorAgentId: type: - string - 'null' format: uuid description: Agent actor id, when actorType is agent actorRunId: type: - string - 'null' format: uuid description: >- Run responsible for this entry, stored as chats.id actorUserName: type: - string - 'null' description: >- Resolved display name for a human actor, hydrated for rendering actorUserImageUrl: type: - string - 'null' description: >- Resolved avatar image URL for a human actor, when one is available actorAgentName: type: - string - 'null' description: >- Resolved display name for an agent actor or referenced assigned agent kind: type: string const: external_event bodyMarkdown: type: - string - 'null' description: Timeline body, when this entry has prose content beforeStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status before a status transition afterStatus: type: - string - 'null' enum: - open - in_progress - escalated - closed_true_positive - closed_false_positive - closed_true_positive_benign - null description: Status after a status transition metadata: type: object additionalProperties: true description: >- Metadata for externally mirrored alert timeline entries. required: - id - organizationId - alertId - createdAt - actorType - actorUserId - actorAgentId - actorRunId - actorUserName - actorUserImageUrl - kind - bodyMarkdown - beforeStatus - afterStatus - metadata totalCount: type: integer minimum: 0 description: Total number of timeline entries for this alert required: - entries - totalCount '400': description: Bad request — input validation failed or the request was malformed content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized — missing or invalid API key / session content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Forbidden — the authenticated user lacks the required permissions content: application/json: schema: $ref: '#/components/schemas/PermissionError' '500': description: Internal server error content: application/json: schema: $ref: '#/components/schemas/Error' x-codeSamples: - lang: shell label: cURL source: |- curl -X GET "https://app.cotool.ai/api/alerts/:alertId/timeline" \ -H "Authorization: Bearer YOUR_API_KEY" \ -H "Content-Type: application/json" components: schemas: ValidationError: type: object properties: error: type: string description: Error message describing what went wrong issues: type: array description: >- Detailed validation issues, present when request or response schema validation fails items: type: object additionalProperties: true required: - error Error: type: object properties: error: type: string description: Error message describing what went wrong required: - error PermissionError: type: object properties: error: type: string description: Error message describing what went wrong missingPerms: type: array description: Permissions the authenticated user is missing for this operation items: type: string required: - error securitySchemes: ApiKeyAuth: type: http scheme: bearer bearerFormat: API Key description: >- API Key authentication for programmatic access. Include your API key in the Authorization header as: `Bearer your_api_key_here` ````