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", // < 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 //7bdt5ca661 execute api eu west 1 amazonaws com/api/conversations query parameters parameter required format/notes org id required your organization 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 new filter conversations by a specific username headers authorization bearer \<token from step 1 > filter by username the username field is now included in conversation logs via the api this allows you to map each conversation directly to a specific user to enable this, you must define the data username field when embedding the digital human on your website html embed configuration \<div id="talking head" data api base="\[https //chat origin api unith live]\(https //chat origin api unith live)" data api key="your api key" data org id="u 760" data head id="unith 1595" data theme="demo" data username="roman" < define the username here \>\</div> the returned session id will automatically include the username for easy identification "session id" "{{sessionid}} {{username}}" 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 roman", "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/api/conversations?org id=your org id\&start date=2023 06 01t00 00 00z\&end date=2025 06 01t00 00 00z\&head id=" \\ h "authorization bearer your token here" step 3 get session logs retrieve the detailed message logs (the full transcript) for a specific conversation session endpoint get https //7bdt5ca661 execute api eu west 1 amazonaws com/api/sessions/{org id}/{session id} path parameters 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 //7bdt5ca661 execute api eu west 1 amazonaws com/api/sessions/your 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 //7bdt5ca661 execute api eu west 1 amazonaws com/api/conversations?org id=your 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 //7bdt5ca661 execute api eu west 1 amazonaws com/api/sessions/your 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