Models & spend

The model connection determines which model service Offices use. Choose it centrally in Organization › Models & spend, not separately for each Office. The spend report shows where usage goes so you can set limits.

Use the platform’s model

Use Platform model if you do not want to supply an API key or ChatGPT subscription.

1. Find Platform model under Model endpoints.
2. If it is not selected, select Use this one.

The row shows In use by this organisation. If it already does, no action is needed.

Add your own API model endpoint

Save a company-approved model service as an endpoint for the organization to use.

1. Select Add endpoint.
2. Enter:
   • API schema: the menu offers OpenAI Chat Completions.
   • Name: a connection name colleagues recognize.
   • Endpoint URL: the OpenAI-compatible base path, such as https://models.example.com/v1.
   • API key: the key from your provider.
   • Model name: exactly as the provider writes it.
   • Context window (tokens): the provider’s published capacity. Tokens measure model text usage; the context window is the amount it can process at once. See the Glossary.
3. Select Add endpoint.

The endpoint appears in the list. Select Use this one before Offices use it.

Connect a ChatGPT subscription

ChatGPT subscriptions sign in with a one-time code and need no API key. Adding a subscription creates connection settings only. It does not sign in or change the organization’s model.

1. Select Add subscription, enter Name, Model name, and Context window (tokens), then select Add subscription. Use OpenAI’s exact model name for that subscription.
2. Select Connect on its row.
3. Open the link under Sign in to ChatGPT, sign in with the ChatGPT account the organization will use, and enter the displayed One-time code.
4. Return to the original Soulhall page, wait for it to show a successful sign-in, then select Confirm.
5. Once the state is Connected, select Use this one.

Confirm links this sign-in to the subscription. Use this one makes the organization use it.

State or situation	What to do
Not connected	Select Connect, then sign in and confirm.
Sign in again, Revoked	Select Connect again, then sign in and confirm again.
Code expired	Connect again for a new code.
Sign-in state could not be read; Check again appears	Check again first. A connection failure does not mean sign-in was cancelled.
Sign-in started in another browser session	Return to the page where it started. Only that page shows the code and confirmation. Or cancel on the current page and start again.

To change the subscription’s model name or capacity, select Model settings, edit them, and select Save model settings. Changes apply from the next request without signing in again.

Switch the organization’s model connection

Select Use this one on the endpoint you want and check In use by this organisation. To return to the platform connection, do this on the Platform model row.

Switching takes effect from the next request. You do not need to restart Embodiments, reapply settings, or clear conversations.

Clear individual endpoints retained by Embodiments

If the page warns that some Embodiments still use their own endpoints, clear them before changing the organization’s model connection.

1. Select Clear Embodiment endpoints and confirm.
2. After clearing succeeds, choose the model connection you want.

Those Embodiments use the organization’s model from the next request. Clearing may also be rejected for unfinished turns or calls with uncertain outcomes. This handles existing individual settings; it is not a way to create per-Embodiment model settings.

Choose an endpoint for knowledge extraction

Knowledge extraction processes what Embodiments learn from conversations. Its connection is configured separately from the Office conversation model.

1. Under Knowledge extraction, choose Default or an existing API endpoint in model provider.
2. For a custom endpoint, enter Model name.
3. Select Save.

The settings apply to this organization’s knowledge extraction. Default uses the platform’s extraction settings.

Adjust how long to wait for an unreadable result

A turn is one cycle in which an Embodiment receives work, performs it, and replies. If it was sent but the result cannot be read back, Soulhall keeps observing instead of sending it again.

1. In Turn recovery, enter Turn recovery window (minutes) as an integer from 1 to 1440.
2. Select Save.

This window applies to all Offices in the organization. It determines how long observation continues before waiting stops, not the maximum duration of a model turn. See Troubleshooting for unreadable turns.

See where usage goes

1. In Organization › Models & spend, select Open the spend report.
2. Check Total, then use By Embodiment, By Office, and By day under Breakdown to find usage sources.

Field	How to read it
Est. cost	Model cost estimates reported by Embodiments, in US dollars.
Calls	Model API calls, not messages you send in conversations.
Read	Input tokens, including usage read from cache.
Written	Output tokens.

Token counts are shown in millions; 1.0M means one million. Total is recorded cumulative usage. By day shows the latest 14 days, grouped by when usage reports arrived. Breakdown tables show estimated cost, calls, and read tokens; written tokens appear in the total.

Through Soulhall shows calls Soulhall records itself: Calls, Refused, Read, and Written. If Embodiments report calls but this section is zero, the page warns that calls bypassed Soulhall. Ask an Admin or deployment operator to check.

Set organization and Office usage limits

Review actual usage before deciding how much to allow. Limits count input plus output tokens, not dollars.

1. Find Organization (every office) under Token limits in the spend report.
2. Enter Daily limit, millions of tokens and select Save. This combined limit is required and cannot be unlimited.
3. To limit an Office, enter a limit on its row and Save. A blank field sets no separate Office limit; the organization limit still applies.

Compare actual usage under Used (24h). When the Office or organization reaches its limit, later model calls pause and the report shows Stopped. Calls resume only after usage in the past 24 hours falls below the limit.

Related pages

• Admin: set up your organization
• Assign work in a conversation
• Knowledge
• Troubleshooting