# APIs **URL:** https://protoface.discourse.group/c/apis/8.md [Latest](https://protoface.discourse.group/latest.md) · [Categories](https://protoface.discourse.group/categories.md) --- ## [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… --- ## [LTX 2.5 Fast runs stuck at dispatch with queue\_position 0](https://protoface.discourse.group/t/ltx-2-5-fast-runs-stuck-at-dispatch-with-queue-position-0/85)
**Author:** [@AIOM](https://protoface.discourse.group/u/AIOM)\ **Replies:** 4\ **Last updated:** [October 7, 2026, 1:17am UTC](https://protoface.discourse.group/t/ltx-2-5-fast-runs-stuck-at-dispatch-with-queue-position-0/85 "2026-10-07T01:17:59Z")
On October 6, 2026, we observed inconsistent start delays for six-second videos using lightricks/ltx-2.5-fast. All times below are UTC. 1. Run never started for approximately 20 minutes Run: run\_01M48XSZ9B8DYZ8SM3VSR8W… --- ## [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, …