Get conversations by date range

Retrieves conversations for all avatars owned by the authenticated user within a given time range. The range must not exceed 24 hours.

GET /api/v1/conversations

Example Request

curl --location --request GET 'https://api-prd.moonscale.com/api/v1/conversations?dateStart=1700000000&dateEnd=1700086400' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>'

Response

{
    "conversations": [
        {
            "conversationId": "uuid",
            "startTimestamp": "2024-01-01T00:00:00.000Z",
            "durationSeconds": 120,
            "utm_id": "contact-id",
            "utm_source": "source",
            "transcript": [
                {
                    "role": "assistant",
                    "type": "type",
                    "text": "text",
                    "timestamp": "2024-01-01T00:00:00.000Z"
                }
            ],
            "summary": "AI-generated summary of the conversation",
            "liveAvatarId": "uuid"
        }
    ]
}

Headers

x-api-key · string · required

Your Moonscale API key used for authentication.

Content-Type · string

The content type of the request body. Always application/json.

Parameters

dateStart · integer · required

Start of the time range as a Unix timestamp (seconds since epoch).

dateEnd · integer · required

End of the time range as a Unix timestamp (seconds since epoch). Must be after dateStart and within 24 hours.

liveAvatarId · string

Optional live avatar ID (UUID) to filter conversations to a specific avatar.

Example Request

curl --location --request GET 'https://api-prd.moonscale.com/api/v1/conversations?dateStart=1700000000&dateEnd=1700086400' \
--header 'Content-Type: application/json' \
--header 'x-api-key: <YOUR_API_KEY>'

Response

{
    "conversations": [
        {
            "conversationId": "uuid",
            "startTimestamp": "2024-01-01T00:00:00.000Z",
            "durationSeconds": 120,
            "utm_id": "contact-id",
            "utm_source": "source",
            "transcript": [
                {
                    "role": "assistant",
                    "type": "type",
                    "text": "text",
                    "timestamp": "2024-01-01T00:00:00.000Z"
                }
            ],
            "summary": "AI-generated summary of the conversation",
            "liveAvatarId": "uuid"
        }
    ]
}

Responses

---

200:

conversations · Conversation[]

An array of conversation objects within the specified date range.

Show Conversation

conversationId · string

Unique identifier (UUID) of the conversation.

startTimestamp · string | null

ISO 8601 timestamp of when the conversation started.

durationSeconds · integer | null

Duration of the conversation in seconds.

utm_id · string | null

The Contact ID passed via URL (utm_id parameter).

utm_source · string | null

The UTM source parameter from the conversation URL.

transcript · Transcript[] | null

An array of transcript entries for the conversation.

Show Transcript

role · string

Indicates the role of the participant (e.g., “user”, “assistant”).

text · string

The textual content of the message.

timestamp · string

A datetime timestamp marking when the message was sent.

type · string

Specifies the type of the transcription entry.

summary · string | null

AI-generated summary of the conversation.

liveAvatarId · string

The ID (UUID) of the live avatar that hosted this conversation.

---

400:

Invalid query parameters (missing dateStart/dateEnd, range exceeds 24h, or dateEnd not after dateStart).

---

401:

Unauthorized - invalid or missing API key.