# Get X publishing credits Canonical URL: https://sosoapi.ai/docs/api/studio-api-x-usage Contract: sha256:563d2d581da0ad29 Read the Organization X publishing credits shared by this Workspace. Needs workspace_id. Free gets 10 once; Pro gets 100 per billing period. Text costs 1, text containing a URL costs 10. Optional text quotes its cost. This reads stored allowance and calls no X API. POST /studio-api/x/usage ## Authentication and permissions - **Accepted credential classes:** user_session, delegated_oauth, personal_access_token - **Delegated capability:** agent:operate - **Minimum workspace role:** viewer - **Access scope:** Resources this user is authorized to access - **All-workspace consent required:** No - **Changes state:** No - **When the operation is complete:** synchronous_http_response A token can use only the rights held by its owner. Each request checks workspace membership, resource ownership, selected workspaces and granted capabilities. Core and full profiles change which tools are displayed; they do not grant access. ## Request fields ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "text": { "type": "string", "maxLength": 4096 } }, "required": [ "workspace_id" ], "additionalProperties": false } ``` ## Response and completion Success HTTP statuses: 200 A successful HTTP response can mean that a request was accepted rather than completed. For background work, save the returned ID and check the same operation until it finishes. A scheduled or accepted post is published only when the platform confirms it; a client timeout does not establish the result. ```json { "$schema": "https://json-schema.org/draft/2020-12/schema", "type": "object", "properties": { "workspace_id": { "type": "string", "format": "uuid", "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$" }, "plan": { "type": "string", "enum": [ "free", "founding_pro" ] }, "allowance": { "type": "string", "enum": [ "one_time", "monthly" ] }, "period_start": { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, "period_end": { "anyOf": [ { "type": "string", "format": "date-time", "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d(?::[0-5]\\d(?:\\.\\d+)?)?(?:Z|([+-](?:[01]\\d|2[0-3]):[0-5]\\d)))$" }, { "type": "null" } ] }, "limit": { "anyOf": [ { "type": "number", "const": 10 }, { "type": "number", "const": 100 } ] }, "reserved": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "consumed": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "remaining": { "type": "integer", "minimum": 0, "maximum": 9007199254740991 }, "costs": { "type": "object", "properties": { "text": { "type": "number", "const": 1 }, "with_url": { "type": "number", "const": 10 } }, "required": [ "text", "with_url" ] }, "draft_credits": { "anyOf": [ { "type": "number", "const": 1 }, { "type": "number", "const": 10 } ] } }, "required": [ "workspace_id", "plan", "allowance", "period_start", "period_end", "limit", "reserved", "consumed", "remaining", "costs" ] } ``` ## Errors and safe retries Check the HTTP status and response body. A 400 validation error may contain a ZodError; handler errors use error, message and code fields. Keep request_id or x-request-id for diagnosis, without credentials. Fix 401/403 access errors before retrying, and follow Retry-After for 429. If a write is uncertain or returns 5xx, read the existing result first. Reuse an idempotency key only where supported; retry behaviour varies by operation and does not guarantee exactly-once delivery. ## Examples These examples use fictional values checked against the schemas. Replace the IDs with ones you are authorized to use, the media with ready assets and the dates with your confirmed publishing time. Check the account’s eligibility before submitting a write. This page sends no API requests. Set SOSOAPI_ACCESS_TOKEN on your server to a credential accepted by this operation, and keep it out of browser code. For an agent, use sosoapi auth login to sign in through the browser and let the CLI refresh its credentials. request.json ```json { "workspace_id": "11111111-1111-4111-8111-111111111111" } ``` cURL ```bash curl --request POST \ "https://gqeshlawtcexsapabaui.supabase.co/functions/v1/studio-api/x/usage" \ -H "Authorization: Bearer $SOSOAPI_ACCESS_TOKEN" \ -H "Content-Type: application/json" \ --data-binary @request.json ``` JavaScript ```js // Server-side JavaScript. Do not print tokens or credential-bearing responses. const token = process.env.SOSOAPI_ACCESS_TOKEN; if (!token) throw new Error("Set an accepted credential for this operation"); const response = await fetch("https://gqeshlawtcexsapabaui.supabase.co/functions/v1/studio-api/x/usage", { method: "POST", headers: { "Content-Type": "application/json", Authorization: "Bearer " + token }, body: JSON.stringify({ "workspace_id": "11111111-1111-4111-8111-111111111111" }) }); const result = await response.json(); // Check response.ok, the operation-specific body and completion state before continuing. ``` CLI ```bash npx sosoapi api post /studio-api/x/usage < request.json ``` Synthetic response example ```json { "workspace_id": "11111111-1111-4111-8111-111111111111", "plan": "free", "allowance": "one_time", "period_start": "2099-01-15T09:00:00Z", "period_end": null, "limit": 10, "reserved": 0, "consumed": 0, "remaining": 0, "costs": { "text": 1, "with_url": 10 } } ``` ## Related tools and guides MCP: sosoapi_get_x_usage [API reference](https://sosoapi.ai/docs/api)