# Latest **URL:** https://protoface.discourse.group/latest.md?page=1 [Latest](https://protoface.discourse.group/latest.md) · [Categories](https://protoface.discourse.group/categories.md) **Page:** 2 --- ## [The avatar participant never appears in my LiveKit room. What should I check?](https://protoface.discourse.group/t/the-avatar-participant-never-appears-in-my-livekit-room-what-should-i-check/49)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 6:23pm UTC](https://protoface.discourse.group/t/the-avatar-participant-never-appears-in-my-livekit-room-what-should-i-check/49 "2026-07-06T18:23:30Z")
First, confirm avatar.start(...) completed without raising an exception. Check that the avatar is starting in the same LiveKit room as your agent, and that LIVEKIT\_URL, LiveKit credentials, and your Protoface API key are… --- ## [When should I call avatar.start(...) in my LiveKit Agent?](https://protoface.discourse.group/t/when-should-i-call-avatar-start-in-my-livekit-agent/48)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 6:14pm UTC](https://protoface.discourse.group/t/when-should-i-call-avatar-start-in-my-livekit-agent/48 "2026-07-06T18:14:52Z")
Call await avatar.start(session, room=ctx.room) before session.start(...). That gives the avatar participant time to join the LiveKit room, and lets the plugin route the agent’s audio to the avatar correctly. In practic… --- ## [Why does the plugin need my LiveKit API secret if Protoface never receives it?](https://protoface.discourse.group/t/why-does-the-plugin-need-my-livekit-api-secret-if-protoface-never-receives-it/47)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 6:13pm UTC](https://protoface.discourse.group/t/why-does-the-plugin-need-my-livekit-api-secret-if-protoface-never-receives-it/47 "2026-07-06T18:13:32Z")
The plugin uses your LiveKit API secret locally to create a short-lived room token for the avatar participant. Protoface does not need your LiveKit API secret itself. It only receives the temporary worker token that let… --- ## [Livekit-plugins-protoface says credentials are missing. Which environment variables do I need?](https://protoface.discourse.group/t/livekit-plugins-protoface-says-credentials-are-missing-which-environment-variables-do-i-need/46)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 6:12pm UTC](https://protoface.discourse.group/t/livekit-plugins-protoface-says-credentials-are-missing-which-environment-variables-do-i-need/46 "2026-07-06T18:12:01Z")
You will usually need these environment variables in your agent or server environment: PROTOFACE\_API\_KEY, LIVEKIT\_URL, LIVEKIT\_API\_KEY, and LIVEKIT\_API\_SECRET. You can also pass these values directly to AvatarSession or… --- ## [What should I include when reporting an API bug?](https://protoface.discourse.group/t/what-should-i-include-when-reporting-an-api-bug/45)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 6:10pm UTC](https://protoface.discourse.group/t/what-should-i-include-when-reporting-an-api-bug/45 "2026-07-06T18:10:14Z")
When reporting an API bug, please include the endpoint and method, a sanitized request body, the response status, the full error envelope, and the X-Request-Id if you have it. It also helps to include the timestamp, and… --- ## [How do I find sessions for a specific avatar or time window?](https://protoface.discourse.group/t/how-do-i-find-sessions-for-a-specific-avatar-or-time-window/44)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 6:05pm UTC](https://protoface.discourse.group/t/how-do-i-find-sessions-for-a-specific-avatar-or-time-window/44 "2026-07-06T18:05:42Z")
Use the session list endpoint with filters. You can pass avatar\_id to show sessions for one avatar, and use created\_after or created\_before to narrow the time window. You can also filter by status, including grouped val… --- ## [When should I use /v1/usage instead of the session usage field?](https://protoface.discourse.group/t/when-should-i-use-v1-usage-instead-of-the-session-usage-field/43)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 6:00pm UTC](https://protoface.discourse.group/t/when-should-i-use-v1-usage-instead-of-the-session-usage-field/43 "2026-07-06T18:00:52Z")
Use the session’s usage field when you care about one specific session, especially while it is still running. Use /v1/usage for account-level reporting, billing checks, or reconciliation across many sessions. It may lag… --- ## [Why did my requested max\_duration\_seconds get lowered?](https://protoface.discourse.group/t/why-did-my-requested-max-duration-seconds-get-lowered/42)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 5:57pm UTC](https://protoface.discourse.group/t/why-did-my-requested-max-duration-seconds-get-lowered/42 "2026-07-06T17:57:15Z")
Protoface caps session length based on your plan. If you request at max\_duration\_seconds value above your plan limit, the session will use the lower allowed value instead. You can check the session response to see the e… --- ## [What is the difference between 429 rate\_limit, 429 quota\_exceeded, and 503 at\_capacity?](https://protoface.discourse.group/t/what-is-the-difference-between-429-rate-limit-429-quota-exceeded-and-503-at-capacity/41)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 5:51pm UTC](https://protoface.discourse.group/t/what-is-the-difference-between-429-rate-limit-429-quota-exceeded-and-503-at-capacity/41 "2026-07-06T17:51:00Z")
429 rate\_limit means requests are coming in too fast. 429 quota\_exceeded means you have hit a plan limit, such as concurrent sessions. Retrying immediately usually will not help unless a session ends or your limit chang… --- ## [My session says queued, starting, running, ending, or failed. What does that mean?](https://protoface.discourse.group/t/my-session-says-queued-starting-running-ending-or-failed-what-does-that-mean/40)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 5:47pm UTC](https://protoface.discourse.group/t/my-session-says-queued-starting-running-ending-or-failed-what-does-that-mean/40 "2026-07-06T17:47:51Z")
A session may move from created to queued, then starting, running, ending, and finally ended. If something goes wrong it becomes failed, and if it is stopped before it starts it may become canceled. The final states are… --- ## [How should I use Idempotency-Key when retrying session creation?](https://protoface.discourse.group/t/how-should-i-use-idempotency-key-when-retrying-session-creation/39)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 5:43pm UTC](https://protoface.discourse.group/t/how-should-i-use-idempotency-key-when-retrying-session-creation/39 "2026-07-06T17:43:25Z")
Use one unique Idempotency-Key per intended session. If you need to retry, send the same request body with the same key. Reusing that key with a different body can cause a conflict. Keys are remembered for 24 hours, so … --- ## [Why does GET /v1/sessions/{id} show worker\_token: "\[redacted\]"?](https://protoface.discourse.group/t/why-does-get-v1-sessions-id-show-worker-token-redacted/38)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 5:32pm UTC](https://protoface.discourse.group/t/why-does-get-v1-sessions-id-show-worker-token-redacted/38 "2026-07-06T17:32:33Z")
That is expected. LiveKit worker tokens are treated as write-only secrets. Protoface accepts the token when you create the session so the avatar can join the LiveKit room, but it does not echo the token back in later re… --- ## [Should I call the Protoface API directly from my browser?](https://protoface.discourse.group/t/should-i-call-the-protoface-api-directly-from-my-browser/37)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 5:31pm UTC](https://protoface.discourse.group/t/should-i-call-the-protoface-api-directly-from-my-browser/37 "2026-07-06T17:31:41Z")
No. Don’t call the Protoface API directly from the browser. Keep your PROTOFACE\_API\_KEY, LiveKit API secrets, and worker-token minting on a trusted backend, never in browser or mobile client code. The browser should onl… --- ## [What is the smallest valid REST request to start a LiveKit avatar session?](https://protoface.discourse.group/t/what-is-the-smallest-valid-rest-request-to-start-a-livekit-avatar-session/36)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 5:15pm UTC](https://protoface.discourse.group/t/what-is-the-smallest-valid-rest-request-to-start-a-livekit-avatar-session/36 "2026-07-06T17:15:03Z")
The smallest request needs your Protoface Bearer API key plus the session details: avatar\_id, transport.type set to livekit, the LiveKit url, room\_name, and a worker\_token. Mint the LiveKit worker token on your server, … --- ## [How do I request higher concurrency, longer sessions, or production support?](https://protoface.discourse.group/t/how-do-i-request-higher-concurrency-longer-sessions-or-production-support/35)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 5:13pm UTC](https://protoface.discourse.group/t/how-do-i-request-higher-concurrency-longer-sessions-or-production-support/35 "2026-07-06T17:13:32Z")
For higher concurrency, longer sessions, or production support, contact the team through protoface.com/enterprise. Include your expected concurrent sessions, monthly minutes, daily active users, launch timeline, geograp… --- ## [My API key is missing, revoked, or returns 401 authentication. What should I do?](https://protoface.discourse.group/t/my-api-key-is-missing-revoked-or-returns-401-authentication-what-should-i-do/34)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 5:11pm UTC](https://protoface.discourse.group/t/my-api-key-is-missing-revoked-or-returns-401-authentication-what-should-i-do/34 "2026-07-06T17:11:09Z")
A 401 authentication error usually means the key is missing, malformed, revoked, or used with the wrong environment. Check Authorization: Bearer ..., remove extra whitespace, and confirm the base URL matches the key. If… --- ## [Why am I getting 402 insufficient\_credit\_balance when I thought I had credits?](https://protoface.discourse.group/t/why-am-i-getting-402-insufficient-credit-balance-when-i-thought-i-had-credits/32)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 5:09pm UTC](https://protoface.discourse.group/t/why-am-i-getting-402-insufficient-credit-balance-when-i-thought-i-had-credits/32 "2026-07-06T17:09:28Z")
402 insufficient\_credit\_balance means there are not enough usable credits for that action. Historical usage is not the same thing as remaining usable credits. Check your billing state, free monthly credits, purchased cr… --- ## [Why did a short test session consume a full minute of usage?](https://protoface.discourse.group/t/why-did-a-short-test-session-consume-a-full-minute-of-usage/31)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 5:08pm UTC](https://protoface.discourse.group/t/why-did-a-short-test-session-consume-a-full-minute-of-usage/31 "2026-07-06T17:08:15Z")
Short sessions are rounded up to the nearest full minute, so even a few seconds can count as a full usage minute. One credit equals one rounded-up session minute. Usage may draw from free monthly credits or purchased cr… --- ## [What logs are safe to share publicly?](https://protoface.discourse.group/t/what-logs-are-safe-to-share-publicly/30)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 4:52pm UTC](https://protoface.discourse.group/t/what-logs-are-safe-to-share-publicly/30 "2026-07-06T16:52:21Z")
Safe to share: request IDs, session IDs, error types or codes, timestamps, package versions, and session statuses. Please redact API keys, LiveKit secrets, JWTs, LiveKit room tokens, worker tokens, customer PII, private… --- ## [A Protoface session failed. What should I include in my forum post?](https://protoface.discourse.group/t/a-protoface-session-failed-what-should-i-include-in-my-forum-post/29)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 4:51pm UTC](https://protoface.discourse.group/t/a-protoface-session-failed-what-should-i-include-in-my-forum-post/29 "2026-07-06T16:51:43Z")
Please include the endpoint or plugin path you used, session\_id, request\_id, full error envelope, including error.code and error.request\_id, timestamp with timezone, avatar ID, SDK/plugin version, and sanitized logs. Al… --- ## [My session is stuck in queued or starting. What should I check?](https://protoface.discourse.group/t/my-session-is-stuck-in-queued-or-starting-what-should-i-check/28)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 4:50pm UTC](https://protoface.discourse.group/t/my-session-is-stuck-in-queued-or-starting-what-should-i-check/28 "2026-07-06T16:50:51Z")
queued means the session is waiting for a worker. starting means a worker has picked it up and is preparing the avatar, joining LiveKit, or loading assets. Check GET /v1/sessions/{id} for created\_at, started\_at, first\_f… --- ## [How do I isolate whether a problem is in my app, LiveKit, my avatar, or Protoface?](https://protoface.discourse.group/t/how-do-i-isolate-whether-a-problem-is-in-my-app-livekit-my-avatar-or-protoface/27)
**Author:** [@proton](https://protoface.discourse.group/u/proton)\ **Replies:** 0\ **Last updated:** [July 6, 2026, 4:48pm UTC](https://protoface.discourse.group/t/how-do-i-isolate-whether-a-problem-is-in-my-app-livekit-my-avatar-or-protoface/27 "2026-07-06T16:48:33Z")
Use a controlled test. First, check status.protoface.com. Then call GET /v1/status, and call GET /v1/avatars with your API key to confirm API access. Next, create a test session with av\_stock\_001. If the stock avatar wo… --- ## [Start Here: Welcome!](https://protoface.discourse.group/t/start-here-welcome/26)
**Author:** [@alpha](https://protoface.discourse.group/u/alpha)\ **Replies:** 0\ **Last updated:** [June 24, 2026, 12:46am UTC](https://protoface.discourse.group/t/start-here-welcome/26 "2026-06-24T00:46:14Z")
Welcome to the Protoface community! This forum is for technical discussions, support questions, product feedback, and examples from people building with Protoface realtime avatars. Please choose the right category when … --- ## [Category purpose and posting rules: Announcements](https://protoface.discourse.group/t/category-purpose-and-posting-rules-announcements/25)
**Author:** [@alpha](https://protoface.discourse.group/u/alpha)\ **Replies:** 0\ **Last updated:** [June 24, 2026, 12:44am UTC](https://protoface.discourse.group/t/category-purpose-and-posting-rules-announcements/25 "2026-06-24T00:44:46Z")
This category is for official updates from the Protoface team. Use Announcements for product updates, release notes, maintenance notices, incident follow-ups, and important changes to the Protoface API, app, docs, or co… --- ## [Category purpose and posting rules: Support](https://protoface.discourse.group/t/category-purpose-and-posting-rules-support/24)
**Author:** [@alpha](https://protoface.discourse.group/u/alpha)\ **Replies:** 0\ **Last updated:** [June 24, 2026, 12:42am UTC](https://protoface.discourse.group/t/category-purpose-and-posting-rules-support/24 "2026-06-24T00:42:57Z")
This category provides assistance for Protoface implementation, general troubleshooting, bug reports, and account or billing inquiries. Use Support if you encounter technical failures, require setup guidance, or need he… --- ## [Category purpose and posting rules: APIs](https://protoface.discourse.group/t/category-purpose-and-posting-rules-apis/23)
**Author:** [@alpha](https://protoface.discourse.group/u/alpha)\ **Replies:** 0\ **Last updated:** [June 24, 2026, 12:42am UTC](https://protoface.discourse.group/t/category-purpose-and-posting-rules-apis/23 "2026-06-24T00:42:16Z")
This category is for questions and discussion about the Protoface API. Use it for topics about session creation, avatars, usage, billing endpoints, authentication, request IDs, error responses, retries, rate limits, quo… --- ## [Category purpose: LiveKit Plugin](https://protoface.discourse.group/t/category-purpose-livekit-plugin/22)
**Author:** [@alpha](https://protoface.discourse.group/u/alpha)\ **Replies:** 0\ **Last updated:** [June 24, 2026, 12:38am UTC](https://protoface.discourse.group/t/category-purpose-livekit-plugin/22 "2026-06-24T00:38:50Z")
This category is for questions about using Protoface with LiveKit. Use it for livekit-plugins-protoface, LiveKit Agents setup, worker tokens, LiveKit rooms, avatar participants, and plugin configuration. For general Pr… --- ## [Category purpose: Avatars & Sessions](https://protoface.discourse.group/t/category-purpose-avatars-sessions/21)
**Author:** [@alpha](https://protoface.discourse.group/u/alpha)\ **Replies:** 0\ **Last updated:** [June 24, 2026, 12:36am UTC](https://protoface.discourse.group/t/category-purpose-avatars-sessions/21 "2026-06-24T00:36:35Z")
This category is for questions about Protoface avatars and realtime avatar sessions. Use it for session lifecycle, session statuses, first-frame timing, latency, session limits, stock avatars, custom avatar uploads, ava… [Previous page](https://protoface.discourse.group/latest.md)