> ## Documentation Index > Fetch the complete documentation index at: https://docs.kosli.com/llms.txt > Use this file to discover all available pages before exploring further. # List trail events > One page of the trail's events, each typed by its `type`. Page by following _links.next and _links.prev, which are absent at the ends of the walk. ## OpenAPI ````yaml https://app.kosli.com/api/v2/openapi.json get /trails/{org}/{flow_name}/{trail_name}/events openapi: 3.1.0 info: title: Kosli API summary: The API for communicating with Kosli description: > # Authentication When making requests against Kosli API, you can authenticate your requests using a bearer token. Set the bearer token in the request Authorization header to a valid API key. API Keys can be personal or for service accounts. Check the [service accounts documentation](https://docs.kosli.com/getting_started/service-accounts/) for details. ## Curl example ```shell curl -H "Authorization: Bearer <>" https://app.kosli.com/api/v2/environments/<> ``` version: '2.0' servers: - url: https://app.kosli.com/api/v2 description: EU - url: https://app.us.kosli.com/api/v2 description: US security: - HTTPBearer: [] paths: /trails/{org}/{flow_name}/{trail_name}/events: get: tags: - Trails summary: List trail events description: |- One page of the trail's events, each typed by its `type`. Page by following _links.next and _links.prev, which are absent at the ends of the walk. operationId: list_trail_events parameters: - name: flow_name in: path required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9\.\-_~]*$ title: Flow Name - name: trail_name in: path required: true schema: type: string pattern: ^[a-zA-Z0-9][a-zA-Z0-9\.\-_~]*$ title: Trail Name - name: org in: path required: true schema: type: string title: Org - name: sort in: query required: false schema: enum: - oldest - newest type: string description: 'Order of the events: `newest` or `oldest` first.' default: newest title: Sort description: 'Order of the events: `newest` or `oldest` first.' - name: anchor_id in: query required: false schema: anyOf: - type: string maxLength: 36 pattern: ^[0-9a-f-]+$ - type: 'null' description: >- Start the page at the event that reported the attestation, override or artifact with this ID. `_links.prev` reaches the events before it. Ignored with a cursor. title: Anchor Id description: >- Start the page at the event that reported the attestation, override or artifact with this ID. `_links.prev` reaches the events before it. Ignored with a cursor. - name: after in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Cursor for the next page. Use the token from a response's _links.next. title: After description: >- Cursor for the next page. Use the token from a response's _links.next. - name: before in: query required: false schema: anyOf: - type: string - type: 'null' description: >- Cursor for the previous page. Use the token from a response's _links.prev. Cannot be combined with after. title: Before description: >- Cursor for the previous page. Use the token from a response's _links.prev. Cannot be combined with after. - name: per_page in: query required: false schema: type: integer maximum: 100 minimum: 1 description: How many events to return per page (max 100). default: 50 title: Per Page description: How many events to return per page (max 100). responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/TrailEventListResponse' '400': description: A cursor that did not come from a link, or both cursors content: application/json: example: message: Invalid cursor. schema: $ref: '#/components/schemas/BadRequestResponseModel' '404': description: Flow, trail or anchor event not found content: application/json: example: message: Flow, trail or anchor event not found schema: $ref: '#/components/schemas/NotFoundResponseModel' security: - HTTPBearer: [] - HTTPBasic: [] components: schemas: TrailEventListResponse: properties: events: items: oneOf: - $ref: '#/components/schemas/TrailStartedEventResponse' - $ref: '#/components/schemas/TrailUpdatedEventResponse' - $ref: '#/components/schemas/TrailAttestationEventResponse' - $ref: '#/components/schemas/TrailAttestationForArtifactEventResponse' - $ref: '#/components/schemas/ArtifactAttestationEventResponse' - $ref: '#/components/schemas/ArtifactReportedEventResponse' - $ref: '#/components/schemas/ArtifactDeploymentEventResponse' - $ref: '#/components/schemas/ArtifactApprovalEventResponse' - $ref: '#/components/schemas/ArtifactStartedRunningEventResponse' - $ref: '#/components/schemas/ArtifactStoppedRunningEventResponse' - $ref: '#/components/schemas/AttestationOverriddenEventResponse' discriminator: propertyName: type mapping: artifact_approval_reported: '#/components/schemas/ArtifactApprovalEventResponse' artifact_attestation_reported: '#/components/schemas/ArtifactAttestationEventResponse' artifact_creation_reported: '#/components/schemas/ArtifactReportedEventResponse' artifact_deployment_reported: '#/components/schemas/ArtifactDeploymentEventResponse' artifact_started_running: '#/components/schemas/ArtifactStartedRunningEventResponse' artifact_stopped_running: '#/components/schemas/ArtifactStoppedRunningEventResponse' attestation_overridden: '#/components/schemas/AttestationOverriddenEventResponse' trail_attestation_for_artifact_reported: '#/components/schemas/TrailAttestationForArtifactEventResponse' trail_attestation_reported: '#/components/schemas/TrailAttestationEventResponse' trail_reported: '#/components/schemas/TrailStartedEventResponse' trail_updated: '#/components/schemas/TrailUpdatedEventResponse' type: array title: Events description: This page of the trail's events, in the requested order _links: additionalProperties: anyOf: - $ref: '#/components/schemas/HALLink' - items: $ref: '#/components/schemas/HALLink' type: array type: object title: Links description: >- `self`, plus `next` and `prev` towards the later and earlier pages of the requested order, each present only while a page exists that way. type: object required: - events - _links title: TrailEventListResponse BadRequestResponseModel: properties: message: type: string title: Message description: Error message errors: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Errors description: Validation errors by field type: object required: - message title: BadRequestResponseModel NotFoundResponseModel: properties: message: type: string title: Message description: Error message errors: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Errors description: Validation errors by field type: object required: - message title: NotFoundResponseModel TrailStartedEventResponse: properties: timestamp: type: number title: Timestamp description: Unix timestamp of the event git_commit_info: anyOf: - $ref: '#/components/schemas/GitCommitInfo' - type: 'null' description: The commit the event was reported for reported_by: type: string title: Reported By description: Display name of who reported the trail description: anyOf: - type: string - type: 'null' title: Description description: Description of the trail origin_url: anyOf: - type: string - type: 'null' title: Origin Url description: URL the trail was reported from external_urls: additionalProperties: $ref: '#/components/schemas/ExternalUrl' type: object title: External Urls description: External links reported with the trail type: type: string const: trail_reported title: Type type: object required: - timestamp - reported_by - type title: TrailStartedEventResponse TrailUpdatedEventResponse: properties: timestamp: type: number title: Timestamp description: Unix timestamp of the event git_commit_info: anyOf: - $ref: '#/components/schemas/GitCommitInfo' - type: 'null' description: The commit the event was reported for reported_by: type: string title: Reported By description: Display name of who reported the trail description: anyOf: - type: string - type: 'null' title: Description description: Description of the trail origin_url: anyOf: - type: string - type: 'null' title: Origin Url description: URL the trail was reported from external_urls: additionalProperties: $ref: '#/components/schemas/ExternalUrl' type: object title: External Urls description: External links reported with the trail type: type: string const: trail_updated title: Type changes: items: type: string type: array title: Changes description: Names of the trail fields changed type: object required: - timestamp - reported_by - type - changes title: TrailUpdatedEventResponse TrailAttestationEventResponse: properties: timestamp: type: number title: Timestamp description: Unix timestamp of the event git_commit_info: anyOf: - $ref: '#/components/schemas/GitCommitInfo' - type: 'null' description: The commit the event was reported for attestation_id: type: string title: Attestation Id description: ID of the attestation reported attestation_type: type: string title: Attestation Type description: Type of the attestation template_reference_name: type: string title: Template Reference Name description: Name of the attestation in the template is_compliant: type: boolean title: Is Compliant description: Whether the attestation is compliant is_reattestation: anyOf: - type: boolean - type: 'null' title: Is Reattestation description: Whether an earlier attestation had this name is_latest: type: boolean title: Is Latest description: Whether this is the trail's current attestation in its slot type_mismatch: type: boolean title: Type Mismatch description: >- Whether this current attestation's type differs from the template's; an earlier attempt is never flagged expected_attestation_type: anyOf: - type: string - type: 'null' title: Expected Attestation Type description: The template's type, when type_mismatch type: type: string const: trail_attestation_reported title: Type type: object required: - timestamp - attestation_id - attestation_type - template_reference_name - is_compliant - is_latest - type_mismatch - type title: TrailAttestationEventResponse TrailAttestationForArtifactEventResponse: properties: timestamp: type: number title: Timestamp description: Unix timestamp of the event git_commit_info: anyOf: - $ref: '#/components/schemas/GitCommitInfo' - type: 'null' description: The commit the event was reported for attestation_id: type: string title: Attestation Id description: ID of the attestation reported attestation_type: type: string title: Attestation Type description: Type of the attestation template_reference_name: type: string title: Template Reference Name description: Name of the attestation in the template is_compliant: type: boolean title: Is Compliant description: Whether the attestation is compliant is_reattestation: anyOf: - type: boolean - type: 'null' title: Is Reattestation description: Whether an earlier attestation had this name is_latest: type: boolean title: Is Latest description: Whether this is the trail's current attestation in its slot type_mismatch: type: boolean title: Type Mismatch description: >- Whether this current attestation's type differs from the template's; an earlier attempt is never flagged expected_attestation_type: anyOf: - type: string - type: 'null' title: Expected Attestation Type description: The template's type, when type_mismatch type: type: string const: trail_attestation_for_artifact_reported title: Type target_artifact: type: string title: Target Artifact description: Template name of the artifact type: object required: - timestamp - attestation_id - attestation_type - template_reference_name - is_compliant - is_latest - type_mismatch - type - target_artifact title: TrailAttestationForArtifactEventResponse ArtifactAttestationEventResponse: properties: timestamp: type: number title: Timestamp description: Unix timestamp of the event git_commit_info: anyOf: - $ref: '#/components/schemas/GitCommitInfo' - type: 'null' description: The commit the event was reported for attestation_id: type: string title: Attestation Id description: ID of the attestation reported attestation_type: type: string title: Attestation Type description: Type of the attestation template_reference_name: type: string title: Template Reference Name description: Name of the attestation in the template is_compliant: type: boolean title: Is Compliant description: Whether the attestation is compliant is_reattestation: anyOf: - type: boolean - type: 'null' title: Is Reattestation description: Whether an earlier attestation had this name is_latest: type: boolean title: Is Latest description: Whether this is the trail's current attestation in its slot type_mismatch: type: boolean title: Type Mismatch description: >- Whether this current attestation's type differs from the template's; an earlier attempt is never flagged expected_attestation_type: anyOf: - type: string - type: 'null' title: Expected Attestation Type description: The template's type, when type_mismatch type: type: string const: artifact_attestation_reported title: Type target_artifact: type: string title: Target Artifact description: Template name of the artifact artifact_fingerprint: type: string title: Artifact Fingerprint description: Fingerprint of the artifact artifact_name: type: string title: Artifact Name description: Name of the artifact type: object required: - timestamp - attestation_id - attestation_type - template_reference_name - is_compliant - is_latest - type_mismatch - type - target_artifact - artifact_fingerprint - artifact_name title: ArtifactAttestationEventResponse ArtifactReportedEventResponse: properties: timestamp: type: number title: Timestamp description: Unix timestamp of the event git_commit_info: anyOf: - $ref: '#/components/schemas/GitCommitInfo' - type: 'null' description: The commit the event was reported for type: type: string const: artifact_creation_reported title: Type artifact_id: type: string title: Artifact Id description: ID of the artifact reported artifact_fingerprint: type: string title: Artifact Fingerprint description: Fingerprint of the artifact artifact_name: type: string title: Artifact Name description: Name of the artifact template_reference_name: type: string title: Template Reference Name description: Name of the artifact in the template type: object required: - timestamp - type - artifact_id - artifact_fingerprint - artifact_name - template_reference_name title: ArtifactReportedEventResponse ArtifactDeploymentEventResponse: properties: timestamp: type: number title: Timestamp description: Unix timestamp of the event git_commit_info: anyOf: - $ref: '#/components/schemas/GitCommitInfo' - type: 'null' description: The commit the event was reported for type: type: string const: artifact_deployment_reported title: Type artifact_fingerprint: type: string title: Artifact Fingerprint description: Fingerprint of the artifact deployment_number: type: integer title: Deployment Number description: Number of the deployment environment_name: type: string title: Environment Name description: Environment deployed to, or `unknown` type: object required: - timestamp - type - artifact_fingerprint - deployment_number - environment_name title: ArtifactDeploymentEventResponse ArtifactApprovalEventResponse: properties: timestamp: type: number title: Timestamp description: Unix timestamp of the event git_commit_info: anyOf: - $ref: '#/components/schemas/GitCommitInfo' - type: 'null' description: The commit the event was reported for type: type: string const: artifact_approval_reported title: Type artifact_fingerprint: type: string title: Artifact Fingerprint description: Fingerprint of the artifact approval_number: type: integer title: Approval Number description: Number of the approval state: type: string title: State description: State of the approval reviewer: anyOf: - type: string - type: 'null' title: Reviewer description: Who reviewed the approval environment_name: anyOf: - type: string - type: 'null' title: Environment Name description: Environment the approval is for type: object required: - timestamp - type - artifact_fingerprint - approval_number - state title: ArtifactApprovalEventResponse ArtifactStartedRunningEventResponse: properties: timestamp: type: number title: Timestamp description: Unix timestamp of the event git_commit_info: anyOf: - $ref: '#/components/schemas/GitCommitInfo' - type: 'null' description: The commit the event was reported for artifact_fingerprint: type: string title: Artifact Fingerprint description: Fingerprint of the artifact template_reference_name: type: string title: Template Reference Name description: Name of the artifact in the template environment_name: type: string title: Environment Name description: Name of the environment snapshot_index: type: integer title: Snapshot Index description: Index of the snapshot type: type: string const: artifact_started_running title: Type type: object required: - timestamp - artifact_fingerprint - template_reference_name - environment_name - snapshot_index - type title: ArtifactStartedRunningEventResponse ArtifactStoppedRunningEventResponse: properties: timestamp: type: number title: Timestamp description: Unix timestamp of the event git_commit_info: anyOf: - $ref: '#/components/schemas/GitCommitInfo' - type: 'null' description: The commit the event was reported for artifact_fingerprint: type: string title: Artifact Fingerprint description: Fingerprint of the artifact template_reference_name: type: string title: Template Reference Name description: Name of the artifact in the template environment_name: type: string title: Environment Name description: Name of the environment snapshot_index: type: integer title: Snapshot Index description: Index of the snapshot type: type: string const: artifact_stopped_running title: Type type: object required: - timestamp - artifact_fingerprint - template_reference_name - environment_name - snapshot_index - type title: ArtifactStoppedRunningEventResponse AttestationOverriddenEventResponse: properties: timestamp: type: number title: Timestamp description: Unix timestamp of the event git_commit_info: anyOf: - $ref: '#/components/schemas/GitCommitInfo' - type: 'null' description: The commit the event was reported for type: type: string const: attestation_overridden title: Type override_attestation_id: type: string title: Override Attestation Id description: ID of the override attestation_name: type: string title: Attestation Name description: Name of the attestation target_artifact: anyOf: - type: string - type: 'null' title: Target Artifact description: Template name of the artifact, for an artifact attestation artifact_fingerprint: anyOf: - type: string - type: 'null' title: Artifact Fingerprint description: Fingerprint of the artifact, for an artifact attestation reason: type: string title: Reason description: Why the attestation was overridden new_compliance_status: type: boolean title: New Compliance Status description: Compliance after the override original_attestation_id: anyOf: - type: string - type: 'null' title: Original Attestation Id description: ID of the attestation overridden; absent for a missing one original_attestation_type: type: string title: Original Attestation Type description: Type of the attestation overridden original_attestation_status: anyOf: - type: boolean - type: 'null' title: Original Attestation Status description: Compliance before the override type: object required: - timestamp - type - override_attestation_id - attestation_name - reason - new_compliance_status - original_attestation_type title: AttestationOverriddenEventResponse HALLink: properties: href: type: string title: Href description: Absolute URL of the linked resource type: object required: - href title: HALLink GitCommitInfo: properties: sha1: type: string title: Sha1 description: The SHA-1 hash of the commit message: anyOf: - type: string - type: 'null' title: Message description: The commit message author: anyOf: - type: string - type: 'null' title: Author description: The commit author branch: anyOf: - type: string - type: 'null' title: Branch description: The branch name timestamp: anyOf: - type: number - type: 'null' title: Timestamp description: The commit timestamp url: anyOf: - type: string - type: 'null' title: Url description: The commit URL type: object required: - sha1 title: GitCommitInfo description: |- Git commit information response model. Excludes author_username, parents, and url from JSON when not present. ExternalUrl: properties: href: type: string title: Href description: The URL fingerprint: anyOf: - type: string - type: 'null' title: Fingerprint description: Optional fingerprint associated with the URL type: object required: - href title: ExternalUrl description: External URL with optional fingerprint for GetTrail response. securitySchemes: HTTPBearer: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.