# List conversation events

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://help.moveworks.com/api-reference/beta-conversations-api/conversations/llms.txt.
> For full documentation content, see https://help.moveworks.com/api-reference/beta-conversations-api/conversations/llms-full.txt.

GET https://api.moveworks.ai/rest/v1beta1/conversations/{conversation_id}/events

Returns system-initiated messages (async responses and proactive notifications) for a conversation. Only final messages are returned, not transient or reasoning messages.

Use `conversation_id = "-"` to query across all conversations. This is useful for reconciliation after receiving a webhook event, to fetch the full set of messages that may have been missed.

Results are ordered chronologically. Use `start_event_id` and `last_event_id` to define a time range based on previously seen event IDs.

Reference: https://help.moveworks.com/api-reference/beta-conversations-api/conversations/list-events

## OpenAPI Specification

```yaml
openapi: 3.1.0
info:
  title: conversations-api
  version: 1.0.0
paths:
  /conversations/{conversation_id}/events:
    get:
      operationId: list-events
      summary: List conversation events
      description: >-
        Returns system-initiated messages (async responses and proactive
        notifications) for a conversation. Only final messages are returned, not
        transient or reasoning messages.


        Use `conversation_id = "-"` to query across all conversations. This is
        useful for reconciliation after receiving a webhook event, to fetch the
        full set of messages that may have been missed.


        Results are ordered chronologically. Use `start_event_id` and
        `last_event_id` to define a time range based on previously seen event
        IDs.
      tags:
        - subpackage_conversations
      parameters:
        - name: conversation_id
          in: path
          description: >-
            Conversation identifier. Use "-" to read events across all
            conversations.
          required: true
          schema:
            type: string
        - name: start_event_id
          in: query
          description: >-
            Exclusive lower bound. Only events after this event ID are returned.
            Typically the last_event_id from a previous poll.
          required: false
          schema:
            type: string
        - name: last_event_id
          in: query
          description: >-
            Inclusive upper bound. Only events up to and including this event ID
            are returned. Must be greater than start_event_id.
          required: false
          schema:
            type: string
        - name: cursor
          in: query
          description: Pagination cursor from a previous response.
          required: false
          schema:
            type: string
        - name: limit
          in: query
          description: 'Maximum number of events to return per page (1-100, default: 20).'
          required: false
          schema:
            type: integer
            default: 20
        - name: Authorization
          in: header
          description: >-
            JWT bearer token authentication. Obtain an access token from the
            Moveworks auth endpoint and include it in the Authorization header
            as 'Bearer <token>'.
          required: true
          schema:
            type: string
        - name: Assistant-Name
          in: header
          description: >-
            The Moveworks assistant identifier that was configured for your
            organization.
          required: true
          schema:
            type: string
      responses:
        '200':
          description: List of events
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListEventsResponse'
        '401':
          description: Unauthorized - Invalid or missing authentication
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedErrorResponse'
        '404':
          description: Not found - Conversation does not exist
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundErrorResponse'
        '429':
          description: Rate limit exceeded
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitExceededErrorResponse'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalErrorResponse'
servers:
  - url: https://api.moveworks.ai/rest/v1beta1
components:
  schemas:
    ActorType:
      type: string
      enum:
        - USER
        - ASSISTANT
      description: Message actor type
      title: ActorType
    PlainTextContentItemType:
      type: string
      enum:
        - PLAIN_TEXT
      description: Content type discriminator
      title: PlainTextContentItemType
    PlainTextContent:
      type: object
      properties:
        text:
          type: string
          description: Plain text content
      required:
        - text
      title: PlainTextContent
    CommonmarkTextContentItemType:
      type: string
      enum:
        - COMMONMARK_TEXT
      description: Content type discriminator
      title: CommonmarkTextContentItemType
    CommonmarkTextContent:
      type: object
      properties:
        text:
          type: string
          description: Commonmark-formatted text content
      required:
        - text
      title: CommonmarkTextContent
    MarkdownTextContentItemType:
      type: string
      enum:
        - MARKDOWN_TEXT
      description: Content type discriminator
      title: MarkdownTextContentItemType
    MarkdownTextContent:
      type: object
      properties:
        text:
          type: string
          description: >-
            Raw markdown text content. Used when Minerva's chat response
            `is_commonmark` is not set.
      required:
        - text
      title: MarkdownTextContent
    Content:
      oneOf:
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/PlainTextContentItemType'
              description: Content type discriminator
            plain_text:
              $ref: '#/components/schemas/PlainTextContent'
          required:
            - type
            - plain_text
          description: PLAIN_TEXT variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/CommonmarkTextContentItemType'
              description: Content type discriminator
            commonmark_text:
              $ref: '#/components/schemas/CommonmarkTextContent'
          required:
            - type
            - commonmark_text
          description: COMMONMARK_TEXT variant
        - type: object
          properties:
            type:
              $ref: '#/components/schemas/MarkdownTextContentItemType'
              description: Content type discriminator
            markdown_text:
              $ref: '#/components/schemas/MarkdownTextContent'
          required:
            - type
            - markdown_text
          description: MARKDOWN_TEXT variant
      discriminator:
        propertyName: type
      description: Message content with type discriminator
      title: Content
    CitationLocation:
      type: object
      properties:
        offset:
          type: integer
          description: >-
            Zero-based character position in the assistant message where the
            citation should be inserted
      required:
        - offset
      title: CitationLocation
    Attribute:
      type: object
      properties:
        key:
          type: string
          description: Attribute name
        value:
          type: string
          description: Attribute value
      required:
        - key
        - value
      description: >-
        Key-value pair for citation display metadata. This is an opaque
        structure that contains rendering hints specific to each citation.
        Clients should not make assumptions about the keys or values present, as
        they may vary based on citation type and context.
      title: Attribute
    Display:
      type: object
      properties:
        title:
          $ref: '#/components/schemas/Content'
          description: Primary heading/identifier with type discriminator
        body:
          $ref: '#/components/schemas/Content'
          description: Body/description content with type discriminator
        attributes:
          type: array
          items:
            $ref: '#/components/schemas/Attribute'
          description: >-
            Opaque key-value metadata for citation display. These attributes
            contain implementation-specific rendering hints and should be
            treated as a black-box by clients. The structure and values may vary
            between citations and should not be relied upon for business logic.
      title: Display
    Citation:
      type: object
      properties:
        location:
          $ref: '#/components/schemas/CitationLocation'
        url:
          type: string
          format: uri
          description: URL to the entity
        display:
          $ref: '#/components/schemas/Display'
      required:
        - location
      title: Citation
    FeedbackOption:
      type: object
      properties:
        callback_id:
          type: string
          description: >-
            Opaque callback identifier. Pass this value to the feedback endpoint
            to submit this rating.
      required:
        - callback_id
      title: FeedbackOption
    MessageFeedback:
      type: object
      properties:
        helpful:
          $ref: '#/components/schemas/FeedbackOption'
          description: >-
            Positive feedback option. Use this callback_id to rate the response
            as helpful.
        unhelpful:
          $ref: '#/components/schemas/FeedbackOption'
          description: >-
            Negative feedback option. Use this callback_id to rate the response
            as unhelpful.
      description: >-
        Feedback options available on an assistant message. When present, this
        message supports feedback and the callback IDs can be used to submit a
        rating.
      title: MessageFeedback
    Message:
      type: object
      properties:
        message_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        conversation_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        response_id:
          type: string
          description: A base-62 identifier prefixed by a short resource type
        actor:
          $ref: '#/components/schemas/ActorType'
        content:
          $ref: '#/components/schemas/Content'
        citations:
          type:
            - array
            - 'null'
          items:
            $ref: '#/components/schemas/Citation'
          description: Entity citations (assistant messages only)
        created_at:
          type: string
          format: date-time
          description: Creation timestamp (ISO 8601)
        feedback:
          oneOf:
            - $ref: '#/components/schemas/MessageFeedback'
            - type: 'null'
          description: >-
            Feedback options for this message. Present only on final assistant
            messages that support feedback. Use the callback IDs to submit a
            rating via the feedback endpoint.
      required:
        - message_id
        - conversation_id
        - response_id
        - actor
        - content
        - created_at
      title: Message
    EventPayload:
      type: object
      properties:
        message:
          $ref: '#/components/schemas/Message'
          description: Present when the event is a message event
      description: Event payload. Currently only message events are supported.
      title: EventPayload
    Event:
      type: object
      properties:
        event_id:
          type: string
          description: Unique event identifier
        conversation_id:
          type: string
          description: Parent conversation identifier
        event_payload:
          $ref: '#/components/schemas/EventPayload'
      required:
        - event_id
        - conversation_id
        - event_payload
      title: Event
    Metadata:
      type: object
      properties:
        next_cursor:
          type:
            - string
            - 'null'
          description: Opaque cursor for next page (null if no more results)
      title: Metadata
    ListEventsResponse:
      type: object
      properties:
        events:
          type: array
          items:
            $ref: '#/components/schemas/Event'
          description: Array of event objects, ordered chronologically
        metadata:
          $ref: '#/components/schemas/Metadata'
      required:
        - events
        - metadata
      title: ListEventsResponse
    UnauthorizedErrorResponseErrorCode:
      type: string
      enum:
        - UNAUTHORIZED
      title: UnauthorizedErrorResponseErrorCode
    UnauthorizedErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/UnauthorizedErrorResponseErrorCode'
        message:
          type: string
      required:
        - code
        - message
      title: UnauthorizedErrorResponseError
    UnauthorizedErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/UnauthorizedErrorResponseError'
      required:
        - error
      description: Error response for unauthorized access
      title: UnauthorizedErrorResponse
    NotFoundErrorResponseErrorCode:
      type: string
      enum:
        - NOT_FOUND
      title: NotFoundErrorResponseErrorCode
    NotFoundErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/NotFoundErrorResponseErrorCode'
        message:
          type: string
      required:
        - code
        - message
      title: NotFoundErrorResponseError
    NotFoundErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/NotFoundErrorResponseError'
      required:
        - error
      description: Error response for resource not found
      title: NotFoundErrorResponse
    RateLimitExceededErrorResponseErrorCode:
      type: string
      enum:
        - RATE_LIMIT_EXCEEDED
      title: RateLimitExceededErrorResponseErrorCode
    RateLimitExceededErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/RateLimitExceededErrorResponseErrorCode'
        message:
          type: string
      required:
        - code
        - message
      title: RateLimitExceededErrorResponseError
    RateLimitExceededErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/RateLimitExceededErrorResponseError'
      required:
        - error
      description: Error response for rate limit exceeded
      title: RateLimitExceededErrorResponse
    InternalErrorResponseErrorCode:
      type: string
      enum:
        - INTERNAL_ERROR
      title: InternalErrorResponseErrorCode
    InternalErrorResponseError:
      type: object
      properties:
        code:
          $ref: '#/components/schemas/InternalErrorResponseErrorCode'
        message:
          type: string
      required:
        - code
        - message
      title: InternalErrorResponseError
    InternalErrorResponse:
      type: object
      properties:
        error:
          $ref: '#/components/schemas/InternalErrorResponseError'
      required:
        - error
      description: Error response for internal server error
      title: InternalErrorResponse
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: >-
        JWT bearer token authentication. Obtain an access token from the
        Moveworks auth endpoint and include it in the Authorization header as
        'Bearer <token>'.

```

## SDK Code Examples

```python Conversations_listEvents_example
import requests

url = "https://api.moveworks.ai/rest/v1beta1/conversations/-/events"

headers = {
    "Assistant-Name": "acmecorp-conversations-rest-api",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Conversations_listEvents_example
const url = 'https://api.moveworks.ai/rest/v1beta1/conversations/-/events';
const options = {
  method: 'GET',
  headers: {
    'Assistant-Name': 'acmecorp-conversations-rest-api',
    Authorization: 'Bearer <token>'
  }
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Conversations_listEvents_example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.moveworks.ai/rest/v1beta1/conversations/-/events"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Assistant-Name", "acmecorp-conversations-rest-api")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Conversations_listEvents_example
require 'uri'
require 'net/http'

url = URI("https://api.moveworks.ai/rest/v1beta1/conversations/-/events")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Assistant-Name"] = 'acmecorp-conversations-rest-api'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Conversations_listEvents_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.moveworks.ai/rest/v1beta1/conversations/-/events")
  .header("Assistant-Name", "acmecorp-conversations-rest-api")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Conversations_listEvents_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.moveworks.ai/rest/v1beta1/conversations/-/events', [
  'headers' => [
    'Assistant-Name' => 'acmecorp-conversations-rest-api',
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Conversations_listEvents_example
using RestSharp;

var client = new RestClient("https://api.moveworks.ai/rest/v1beta1/conversations/-/events");
var request = new RestRequest(Method.GET);
request.AddHeader("Assistant-Name", "acmecorp-conversations-rest-api");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Conversations_listEvents_example
import Foundation

let headers = [
  "Assistant-Name": "acmecorp-conversations-rest-api",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.moveworks.ai/rest/v1beta1/conversations/-/events")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```