Conversation Logs Retrieval

this guide explains the workflow and endpoints required to retrieve and filter detailed conversation logs from the unith platform the log retrieval workflow consists of three main steps authentication , getting conversations , and fetching session logs you can use our conversational logs frontend to access raw conversational logs https //labs unith ai/conversation logs app step 1 authentication 1 1 obtain bearer token to access the logs, you must first obtain a bearer token using your account credentials endpoint post https //platform api unith ai/auth/token request body { "email" "your email\@example com", "secretkey" "your secret key" } curl example curl x post "https //platform api unith ai/auth/token" \\ h "content type application/json" \\ d '{ "email" "your email\@example com", "secretkey" "your secret key" }' the response will contain a json web token (jwt) under data bearer save this token to use in the subsequent api calls as an authorization header response { "data" { "bearer" "eyjhbgcioijiuzi1niisinr5cci6ikpxvcj9 " } } 1 2 retrieve organization id (org id) use the token obtained in the previous step to fetch your user profile, which contains your organization details endpoint get https //platform api unith ai/user/me curl x 'get' \\ '\[https //platform api unith ai/user/me]\(https //platform api unith ai/user/me)' \\ h 'accept application/json' \\ h 'authorization bearer yourbearertoken' response { "id" "youruserid", "organisation" { "id" "thisisyourorgid", "publicid" "thisisyourpublicorgid", // < use this id in all subsequent steps }, } the value of "id" under the " organisation " object is your org id you will need this id for step 2 and step 3 step 2 get conversations (filtering by metadata) retrieve a list of conversation sessions for your organization within a specified date range endpoint get https //api data unith ai/conversations query parameters parameter required format/notes org id required your organization public id start date required start date in iso 8601 format (e g , 2023 09 03t00 00 00z) end date required end date in iso 8601 format (e g , 2026 10 01t00 00 00z) head id optional filter by a specific digital human head id username optional filter conversations by a specific username data tag optional filter conversations by custom data tag headers authorization bearer \<token from step 1 > filter by username the username field is now available as a separate column in conversation logs, making it easier to track and analyze user specific conversations previous behavior username was included as a suffix in session id "sessionid username" required parsing the session id to extract username the returned session id will automatically include the username for easy identification "session id" "{{sessionid}} {{username}}" current behavior username is now available as a dedicated field legacy session id suffix format is still supported for backward compatibility but will be depreciated in the near future recommended use the dedicated username field for cleaner analytics to enable username tracking, define the data username attribute when embedding the digital human html embed configuration \<unith widget head id="unith 1595" org id="u 760" api key="your api key" username="alice" \> \</unith widget> response example below is an example of a retrieved conversation, showing the username included in the session id "conversations" \[ { "session id" "20ab19bf 942b 4fc8 bf36 1bc4d7d53103 alice", "start time" "2025 09 09t06 45 07 211821", "end time" "2025 09 09t06 46 40 504327", "head id" "unith 1595", "head name" null, "org id" "u 760", "message count" 18 } ] curl example (with date range) curl x get "https //7bdt5ca661 execute api eu west 1 amazonaws com/conversations?org id=your public org id\&start date=2023 06 01t00 00 00z\&end date=2025 06 01t00 00 00z\&head id=" \\ h "authorization bearer your token here" custom tracking with data tag the new data tag field enables flexible custom tracking for any use case this field accepts any string value of your choice, allowing you to segment and analyze conversations based on your specific requirements common use cases multi domain tracking track the same digital human across different websites customer segmentation tag conversations by user type (e g , "segment\ enterprise", "segment\ trial") campaign tracking associate conversations with marketing campaigns (e g , "campaign\ summer2025") a/b testing track different variants (e g , "variant\ control", "variant\ test") multiple values example you can use any delimiter format that suits your needs the data tag field gives you complete flexibility—use any format or structure that matches your analytics needs enhanced session metadata the unith platform now includes enhanced metadata fields in conversation logs, providing deeper insights into user sessions and enabling more flexible analytics session data fields direct fields (sent at root level) field what it stores example session id unique session identifier "20ab19bf 942b 4fc8 bf36 1bc4d7d53103" username user's name from session (separate column) "john doe" or "anonymous" data tag custom identifier for tracking and segmentation "nserve\ mobile", "domain\ example com" start time session start timestamp "2025 09 09t06 45 07 211821" end time session end timestamp "2025 09 09t06 46 40 504327" head id digital human identifier "unith 1595" org id organization identifier "u 760" message count number of messages in conversation 18 metadata fields (extracted from request metadata) field what it stores example origin domain website where chat happened "https //chat unith ai" device type user's device "desktop", "mobile", "tablet" browser family user's browser "chrome", "firefox", "safari" language pref user's language preference "en us", "ja jp", "de de" technical metadata fields (origin domain, device type, browser family, language pref) are captured automatically without additional configuration these fields are available in both streaming and legacy digital humans step 3 get session logs retrieve the detailed message logs (the full transcript) for a specific conversation session endpoint get https //api data unith ai/sessions/{public org id}/{session id} path parameters public org id your organization id session id the full session id (including the username suffix, if used) obtained from step 2 headers authorization bearer \<token from step 1> curl example curl x get "https //api data unith ai/sessions/your public org id/session id here" \\ h "authorization bearer your token here" complete workflow example this section provides a complete, sequential command line example for retrieving logs \# step 1 get authentication token (stores token in environment variable $token) token=$(curl s x post "\[https //platform api unith ai/auth/token]\(https //platform api unith ai/auth/token)" \\ h "content type application/json" \\ d '{ "email" "your email\@example com", "secretkey" "your secret key" }' | jq r ' data bearer') \# step 2 get conversations curl x get "https //api data unith ai/conversations?org id=your public org id\&start date=2023 06 01t00 00 00z\&end date=2025 06 01t00 00 00z" \\ h "authorization bearer $token" \# step 3 get specific session logs (replace session id with actual id from step 2) curl x get "https //api data unith ai/sessions/your public org id/session id here" \\ h "authorization bearer $token" important notes token expiration bearer tokens have an expiration time of 7 days if you receive authentication errors, you must generate a new token via the authentication endpoint organization id always ensure you use the correct organization id associated with your account date format all date parameters (start date, end date) must strictly use the iso 8601 format (e g , yyyy mm ddthh\ mm\ ssz) session ids session ids are uuids retrieved from the conversations endpoint, and will include the optional {{username}} suffix if configured in the embed code