Teams

Team Model

Fields

Field

Type

Description
object
"team"
id
string
name
string
created_at
updated_at
deleted_at
| null When the team is scheduled to be deleted; null when it is not.
logo_url
string | null
status
Account standing. Any status other than active stops ingest: delinquent marks a missed payment, restricted also makes the API read-only apart from the billing fields needed to recover the account, and blocked is applied manually by Tailglow.
billing_email
string
billing_plan
billing_address
Postal address that appears on the team's invoices.
storage_gb
number Stored data across the team's projects, in gigabytes of uncompressed data: raw ingested files and artifacts, plus view output and minute-level rollups. Recalculated hourly; billing_updated_at is the last refresh.
billing_period_server_months
number Server-months the team's servers have accrued in the current calendar-month billing period, counted up to the last refresh.
billing_period_input_tokens
number AI input tokens consumed through Tailglow-provided model access this billing period, counting only tokens charged at the full input rate. Anything served from or written to the prompt cache is counted separately below. Chats running on your own provider keys are not counted at all.
billing_period_output_tokens
number AI output tokens consumed through Tailglow-provided model access this billing period.
billing_period_cache_read_tokens
number Input tokens served from the prompt cache this billing period, charged at the cache rate.
billing_period_cache_write_tokens
number Input tokens written to the prompt cache this billing period, charged at the cache rate.
billing_updated_at
| null When the cached billing quantities were last recalculated; null before the first pass.
max_servers_per_project
number How many servers each project may run. Scale requests beyond it are rejected.
is_mfa_required
boolean Whether every member must verify with two-factor authentication before their session can act.
is_tailglow_ai_enabled
boolean Whether members may run the assistant on Tailglow's model, billed to this team. When false, each member must add their own provider key before they can use the assistant at all.
has_payment_method
boolean Whether the team has a payment method on file.
promo_expires_at
| null When the team's free trial window ends. A time in the past means the trial has ended and the trial servers are being settled; null when the team has no trial window.
server_trial_used_at
| null When the team used its once-per-account server trial; retained after the trial is settled.
promo_server_hours
number Shared server-hour credits remaining after the last invoice; unbilled usage is not deducted.
promo_ai_tokens
number Shared Tailglow AI token credits remaining after the last invoice.
tgl_generations_count
number Automatic transform-script generations counted against the hourly budget. The counter rolls over lazily: after the window elapses it keeps its last value until the next generation.
tgl_generations_reset_at
| null When the counted window ends or ended. A past timestamp means no generation has happened since.

Team Billing Model

Fields

Field

Type

Description
is_estimate_complete
boolean False when a saved AI rate needs support; monetary estimates are incomplete until resolved.
object
"billing"
team_id
string
calculated_at
billing_plan
has_payment_method
boolean
promo_expires_at
| null Cardless trial deadline; unused promotional units do not expire at this time.
server_count
number Non-surge capacity across the team, including provisioning and excluding idle/terminating.
uninvoiced_server_hours
number Billable server-hours since the last saved invoice, including preceding-month usage.
promo_server_hours
number Stored server-hour balance after the last invoice.
promo_ai_tokens
number Stored Tailglow-funded token balance after the last invoice.
available_promo_server_hours
number Server-hour credits remaining after accrued, uninvoiced usage.
available_promo_ai_tokens
number Tailglow-funded token credits remaining after accrued, uninvoiced usage.
included_storage_gb_months
number Storage, in GB-months, the plan credits on every monthly invoice.
available_included_storage_gb_months
number Included storage this period has not used yet, in GB-months.
period_start_at
First moment of the billing period being estimated, in UTC.
period_end_at
First moment of the following period, so the period is [start, end).
billed_at
When the invoice for this period is calculated, which is after the period has closed.
line_items
[] One entry per billable line. Lines that accrued nothing are present with a zero quantity.
subtotal_cents
number
discount_cents
number
total_cents
number What the period has accrued so far, after discounts. Excludes tax, which Stripe calculates when the invoice is finalized, and any credit note balance, which is applied at payment.
projected_line_items
[] The same period carried to billed_at: storage held and grown at its recent rate, servers that are up staying up, tokens continuing at the month-to-date rate. A subscription appears unchanged because it is committed for the whole period. A forecast rather than a measurement, so it assumes today's usage continues and moves the moment a server is added or removed. Discounts here are read as of billed_at, so one that lapses mid-period counts toward total_cents but not toward this.
projected_subtotal_cents
number
projected_discount_cents
number
projected_total_cents
number

Billing Line Item Model

Fields

Field

Type

Description
line_item_type
description
string The label this line carries on the issued invoice, so an estimate reads like the bill.
quantity
number Units billed, in the line item's own unit: GB-months, server-months, or token millions.
unit_price_cents
number
subtotal_cents
number
discount_cents
number Zero when no discount applies to this line item.
total_cents
number
discount_id
string | null The negotiated discount applied in addition to promo credits, or null.
discount_percent
number | null Set only for percent discounts; a fixed-amount discount reports its value in cents.

Billing Estimate Model

Fields

Field

Type

Description
line_items
[] One entry per billable line, in the order the invoice lists them. Lines that accrued nothing are present with a zero quantity.
subtotal_cents
number
discount_cents
number
total_cents
number

Address Model

Fields

Field

Type

Description
thoroughfare
string | null Street line: street number and street name.
premise
string | null Unit, suite, or building within the street address.
sublocality
string | null District or neighborhood within the city, where addresses use one.
locality
string | null City or town.
administrative_area
string | null State, province, or region.
postal_code
string | null ZIP or postal code.
country
string | null Two-letter ISO country code.

List Teams

Endpoint

Retrieve a list of teams the caller belongs to.

GET
/v1/teams

Query Parameters

Field

Type

Description
order_by
string Field used to order the teams. Defaults to "name". Accepted values: "created_at","name".
name
TextFilter Filter by team name, written as operator:value. For example contains:acme or equals:Acme Inc.
status
Filter by team status, written as operator:value. For example equals:active or in:active,delinquent.
billing_plan
Filter by billing plan, written as operator:value. For example in:pro_v1,enterprise_v1.
created_at
DateFilter Filter by creation date, written as operator:value. For example gt:2026-01-01 or between:2026-01-01,2026-02-01.
deleted_at
NullableDateFilter Filter by scheduled deletion date. Use null for teams that are not scheduled for deletion, not:null for teams that are.
limit
number Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • API key callers only ever receive the single team the key belongs to.
  • Teams scheduled for deletion are only returned to their Owners.
  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: Team[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve Team

Endpoint

Retrieve a single team.

GET
/v1/teams/:team_id

Path Parameters

Field

Type

Description
team_id
string Unique identifier of the team.

Comments

  • You can only retrieve the team your credentials are scoped to.

Response

200 
{
  message: string;
  data: Team;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Retrieve Team Billing

Endpoint

Retrieve the team's current billing summary.

billing:read
GET
/v1/teams/:team_id/billing

Path Parameters

Field

Type

Description
team_id
string Unique identifier of the team.

Comments

  • Requires billing:read and credentials scoped to this team. Every response includes accrued and projected charges, stored and available promotional credits, and server usage.
  • Available credits account for uninvoiced usage, including the preceding month before its invoice is saved. Reading this summary does not consume credits or create an invoice.
  • Amounts exclude tax and credit notes applied at payment. Projections assume current usage continues; the final invoice can differ.

Response

200 
{
  message: string;
  data: TeamBilling;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Create Team

Endpoint

Create a new team owned by the authenticated user.

POST
/v1/teams

Request Body

Field

Type

Requirement

Description
name
string
Optional
Display name for the team. Minimum length: 2. Maximum length: 60.
billing_email
string (email)
Optional
Email address that receives invoices and billing notifications. Maximum length: 64.
billing_plan
Optional
Billing plan for the team.
status
Optional
Account status for the team.
is_mfa_required
boolean
Optional
Whether every member must sign in with multi-factor authentication.
max_servers_per_project
integer
Optional
Maximum number of servers each project in the team can run. Minimum: 1. Maximum: 1000.
billing_address
object
Optional
Billing address printed on invoices.
logo_url
string
Optional
Team logo, sent as a JPEG or PNG base64 data URI.

Comments

  • Teams cannot be created with an API key. Use a signed-in user session.
  • name defaults to Team and billing_email defaults to the authenticated user's email address when they are omitted.
  • The team starts on the pro_v1 plan with a generated logo. billing_plan, status, logo_url, is_mfa_required, billing_address, and max_servers_per_project are ignored on create. Send them to the update endpoint instead.
  • There is a maximum number of teams a single user can create.
  • The authenticated user is added to the new team as its Owner.
  • billing_email cannot use the @tailglow.io domain.
  • logo_url must be a JPEG or PNG base64 data URI of at most 5 MB.

Response

201 
{
  message: string;
  data: Team;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}

Update Team

Endpoint

Update an existing team.

POST
/v1/teams/:team_id

Path Parameters

Field

Type

Description
team_id
string Unique identifier of the team.

Request Body

Field

Type

Requirement

Description
name
string
Optional
Display name for the team. Minimum length: 2. Maximum length: 60.
billing_email
string (email)
Optional
Email address that receives invoices and billing notifications. Maximum length: 64.
billing_plan
Optional
Billing plan for the team.
status
Optional
Account status for the team.
expected_status
Optional
The status the team had when you loaded it. Required with status; the change is refused if the status has changed since.
is_mfa_required
boolean
Optional
Whether every member must sign in with multi-factor authentication.
is_tailglow_ai_enabled
boolean
Optional
Whether members may run the AI assistant on Tailglow's model, billed to this team. When false, each member must add their own provider key before they can use the assistant.
max_servers_per_project
integer
Optional
Maximum number of servers each project in the team can run. Minimum: 1. Maximum: 1000.
billing_address
object
Optional
Billing address printed on invoices.
logo_url
string
Optional
Team logo, sent as a JPEG or PNG base64 data URI.
deleted_at
| null
Optional
Date and time when the team is scheduled to be permanently deleted.

Comments

  • Teams cannot be updated with an API key. Use a signed-in user session.
  • At least one field must be provided.
  • Only team Owners can change billing, security, or account settings. Other members can update name and logo_url only.
  • status, max_servers_per_project, and deleted_at are managed by Tailglow and cannot be set by team members.
  • status requires expected_status, the status you loaded; the change is refused with a conflict if the team's status has changed since.
  • Changing is_mfa_required requires a recently verified multi-factor sign-in.
  • Moving to a plan that bills a payment method requires a valid payment method on the team.
  • billing_email cannot use the @tailglow.io domain.
  • logo_url must be a JPEG or PNG base64 data URI of at most 5 MB.

Response

200 
{
  message: string;
  data: Team;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Delete Team

Endpoint

Schedule a team for deletion.

DELETE
/v1/teams/:team_id

Path Parameters

Field

Type

Description
team_id
string Unique identifier of the team.

Comments

  • Teams cannot be deleted with an API key. Use a signed-in user session.
  • Only the team Owner can delete a team.
  • The team must be active. Contact support to delete a suspended or blocked team.
  • Deletion is scheduled, not immediate. Permanent removal happens 40 days later, the team's projects and API keys are cancelled, and every signed-in member is signed out. An owner who signs back in before then cancels the deletion.

Response

200 
{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

List Team Members

Endpoint

Retrieve a list of members in a team.

users:read
GET
/v1/teams/:team_id/users

Path Parameters

Field

Type

Description
team_id
string Unique identifier of the team.

Query Parameters

Field

Type

Description
order_by
string Field used to order the team members. Defaults to "name". Accepted values: "created_at","name".
name
TextFilter Filter by member name, written as operator:value. For example contains:riley or starts_with:Ri.
status
Filter by member account status, written as operator:value. For example in:active,blocked.
limit
number Maximum number of items to return. Defaults to 25. Minimum: 1. Maximum: 200.
after
string Cursor from pagination.next_cursor of a previous response. Returns the resources after that page.
before
string Cursor from pagination.prev_cursor of a previous response. Returns the resources before that page.
sort
string Sort direction for the result set. Defaults to "desc". Accepted values: "asc","desc".

Comments

  • You can only list members of the team your credentials are scoped to.
  • after and before are mutually exclusive.

Response

200 
{
  message: string;
  data: User[];
  status: 200;
  error: null;
  pagination: Pagination;
  endpoint: string;
}

Retrieve Team Member

Endpoint

Retrieve a single member of a team.

users:read
GET
/v1/teams/:team_id/users/:user_id

Path Parameters

Field

Type

Description
team_id
string Unique identifier of the team.
user_id
string Unique identifier of the user.

Comments

  • You can only retrieve members of the team your credentials are scoped to.

Response

200 
{
  message: string;
  data: User;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Add Team Member

Endpoint

Add a person to a team. This does not create a standalone user account: an existing Tailglow account is matched by email address, and an account is created for the address only when none exists yet.

users:write
POST
/v1/teams/:team_id/users

Path Parameters

Field

Type

Description
team_id
string Unique identifier of the team.

Request Body

Field

Type

Requirement

Description
name
string
Optional
Display name for the member. Minimum length: 2. Maximum length: 60.
role_id
string
Required
Role the member holds in this team.
email
string (email)
Required
Email address of the person to add. They receive a sign-in link at this address, and an account is created for them if they do not already have one.

Comments

  • The person receives an email with a sign-in link for the team.
  • Someone who is already a member of the team cannot be added again.
  • Only Owners can assign the Owner role.
  • There is a maximum number of members per team.
  • Blocked and locked accounts cannot be added to a team.
  • You can assign only scopes that your own authorization has.

Response

201 
{
  message: string;
  data: User;
  status: 201;
  error: null;
  pagination: null;
  endpoint: string;
}

Update Team Member

Endpoint

Update a member of a team.

users:write
POST
/v1/teams/:team_id/users/:user_id

Path Parameters

Field

Type

Description
team_id
string Unique identifier of the team.
user_id
string Unique identifier of the user.

Request Body

Field

Type

Requirement

Description
name
string
Optional
Display name for the member. Minimum length: 2. Maximum length: 60.
role_id
string
Optional
Role the member holds in this team.

Comments

  • You cannot change your own role.
  • You can only change your own name. Another member's name is theirs to change.
  • You cannot assign a role that holds scopes you do not hold yourself, and only Owners can assign or replace the Owner role.
  • Changing a member's role signs them out and emails them the new role.
  • A member's email address cannot be changed. Remove them and add them again with the new address.

Response

200 
{
  message: string;
  data: User;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Remove Team Member

Endpoint

Remove a member from a team.

users:delete
DELETE
/v1/teams/:team_id/users/:user_id

Path Parameters

Field

Type

Description
team_id
string Unique identifier of the team.
user_id
string Unique identifier of the user.

Comments

  • You cannot remove yourself from a team. Delete the team instead if you are its last member.
  • You cannot remove a member whose role holds scopes you do not hold yourself, and only Owners can remove another Owner.
  • The last Owner of a team cannot be removed.
  • The member is emailed to let them know they were removed. Their Tailglow account is not deleted, only their membership in this team.

Response

200 
{
  message: string;
  data: null;
  status: 200;
  error: null;
  pagination: null;
  endpoint: string;
}

Referenced Types

TextFilter

Text filters use operator:value, for example ?name=contains:acme. Supported operators are equals, not_equals, contains, not_contains, starts_with, not_starts_with, ends_with, not_ends_with, in, not_in, exists and not_exists. Comma-separate the values of in and not_in, as in in:acme,globex.

DateFilter

Date filters use operator:value with an ISO 8601 date, for example ?created_at=gt:2026-01-01. Supported operators are gt, lt and between, and between takes two comma-separated dates. The named ranges today, yesterday, this_month and last_month are also accepted in place of an operator.

NullableDateFilter

Nullable date filters accept everything a date filter accepts, plus null to match records where the field is unset and not:null to match records where it is set.

ISODateString

An ISO 8601 date-time string returned at the JSON API boundary.

TeamStatus

active
delinquent
restricted
blocked

BillingPlan

pro_v1
enterprise_v1

BillingLineItemType

compute
storage
subscription
ai_input
ai_output
ai_cache_read
ai_cache_write