Organization

class lightning_sdk.Organization(name=None)

Bases: Owner

Represents an organization owner of teamspaces and studios.

Parameters:

name (Optional[str]) – the name of the organization
name (str | None)

Note

Arguments will be automatically inferred from environment variables if possible, unless explicitly specified

create_teamspace(name)

Create a new teamspace owned by this organization.

Parameters:

name (str) – The name for the new teamspace.
name (str)

Returns:

The newly created teamspace.

Return type:

Teamspace

get_activity(teamspace=None, teamspaces=None, filters=None, cursor=None)

Get billing activity for this organization, or one or more of its teamspaces.

Returns paginated, per resource rollup rows keyed by raw IDs (no resolved names). For a resolved-name, non-paginated report meant for reading or exporting, use get_session_activity() (one row per session) or get_resource_activity() (one row per resource) instead.

Parameters:

teamspace (Union[str, Teamspace, None]) – A single teamspace to scope the query to.
teamspaces (Optional[List[Union[str, Teamspace]]]) – Multiple teamspaces to scope the query to. Provide at most one of teamspace/teamspaces. If neither is given, the query covers the whole organization.
filters (Optional[BillingActivityFilters]) – Optional filters to narrow down the query.
cursor (Optional[BillingActivityCursor]) – Optional pagination cursor to continue a previous query.
teamspace (str | Teamspace | None)
teamspaces (List[str | Teamspace] | None)
filters (BillingActivityFilters | None)
cursor (BillingActivityCursor | None)

Returns:

The usage report response.

Return type:

BillingActivity

get_activity_filter_values(teamspace=None)

Get the set of values a billing activity query can be filtered by.

Parameters:

teamspace (Union[str, Teamspace, None]) – Optionally scope to a single teamspace. If omitted, covers the whole organization.
teamspace (str | Teamspace | None)

Returns:

The available filter values.

Return type:

BillingActivityFilterValues

get_monthly_summary(start=None, end=None)

Returns a monthly summary of credits purchased, used, and remaining.

Exactly one of start and end must be supplied, or both together:

only start: grabs monthly summaries for months after pivot=start.
only end: grabs monthly summaries for months before pivot=end.
both start and end: acts as a normal range.

Parameters:

start (Optional[datetime]) – Start of the time range. If given without end, acts as an “AFTER” pivot.
end (Optional[datetime]) – End of the time range. If given without start, acts as a “BEFORE” pivot.
start (datetime | None)
end (datetime | None)

Return type:

list[MonthlySummary]

Returns:

A list of MonthlySummary dicts, one per month in the requested range:

[
    {
        "period_start": datetime,
        "period_end": datetime,
        "total_credits_remaining": float,
        "total_credits_purchased": float,
    },
    ...
]

Raises:

ValueError – If neither start nor end is provided, if start is after end, or if an “AFTER” pivot (derived from a lone start) is in the future.

get_resource_activity(writer, format=ActivityFileFormat.JSON, teamspace=None, teamspaces=None, filters=None, cursor=None)

Get the resource-level billing activity report for this organization, as CSV or JSON.

One row per resource (e.g. a Studio or Job) that was active in the queried time range, rather than one row per session; use get_session_activity() for the finer-grained, per-session breakdown of a resource’s activity.

Parameters:

writer (IO[str]) – Writable text stream to write the report to, e.g. an open file, an io.StringIO buffer, or sys.stdout. To get the JSON as a string rather than writing it to a file, pass an io.StringIO() and read it back with .getvalue().
format (ActivityFileFormat) – File format to return the report in, either CSV or JSON. Defaults to JSON.
teamspace (Union[str, Teamspace, None]) – A single teamspace to scope the report to.
teamspaces (Optional[List[Union[str, Teamspace]]]) – Multiple teamspaces to scope the report to. Provide at most one of teamspace/teamspaces.
filters (Optional[BillingActivityFilters]) – Optional filters to narrow down the report.
cursor (Optional[BillingActivityCursor]) – Optional pagination cursor to continue a previous query.
writer (IO[str])
format (ActivityFileFormat)
teamspace (str | Teamspace | None)
teamspaces (List[str | Teamspace] | None)
filters (BillingActivityFilters | None)
cursor (BillingActivityCursor | None)

Return type:

None

get_session_activity(writer, format=ActivityFileFormat.JSON, teamspace=None, teamspaces=None, filters=None, cursor=None)

Get the session-level billing activity report for this organization, as CSV or JSON.

One row per session. A resource (e.g. a Studio or Job) can have many sessions within the queried time range, so this report is the finer-grained of the two; use get_resource_activity() for one row per resource instead.

Parameters:

writer (IO[str]) – Writable text stream to write the report to, e.g. an open file, an io.StringIO buffer, or sys.stdout. To get the JSON as a string rather than writing it to a file, pass an io.StringIO() and read it back with .getvalue().
format (ActivityFileFormat) – File format to return the report in, either CSV or JSON. Defaults to JSON.
teamspace (Union[str, Teamspace, None]) – A single teamspace to scope the report to.
teamspaces (Optional[List[Union[str, Teamspace]]]) – Multiple teamspaces to scope the report to. Provide at most one of teamspace/teamspaces.
filters (Optional[BillingActivityFilters]) – Optional filters to narrow down the report.
cursor (Optional[BillingActivityCursor]) – Optional pagination cursor to continue a previous query.
writer (IO[str])
format (ActivityFileFormat)
teamspace (str | Teamspace | None)
teamspaces (List[str | Teamspace] | None)
filters (BillingActivityFilters | None)
cursor (BillingActivityCursor | None)

Return type:

None

property default_cloud_account: str | None

The organization’s preferred cloud account ID, or None if not set.

Returns:: The preferred cloud account ID.
Return type:: str | None

property id: str: The organization’s ID.

property name: str: The organization’s name.

class lightning_sdk.api.org_api.MonthlySummary

Bases: TypedDict

A single month’s billing summary of credits purchased, used, and remaining.

period_start: Start of the billing period (typically the first of the month).

period_end: End of the billing period (typically the end of the month).

total_credits_remaining: Total credits remaining at the end of the monthly period.

total_credits_purchased: Total credits purchased during the monthly period.

class lightning_sdk.BillingActivityFilters(resource_types=None, resource_ids=None, user_ids=None, start=None, end=None, limit=None)

Bases: object

Filters for narrowing down a billing activity query.

Parameters:

resource_types (List[str] | None)
resource_ids (List[str] | None)
user_ids (List[str] | None)
start (datetime | None)
end (datetime | None)
limit (int | None)

resource_types: Only include activity for these resource types (e.g. “Studio”, “Job”).

resource_ids: Only include activity for these specific resource IDs.

user_ids: Only include activity generated by these users.

start: Only include activity on or after this time.

end: Only include activity on or before this time.

limit: Maximum number of entries to return.

class lightning_sdk.BillingActivityCursor(search_after=None, search_after_resource_id=None, search_after_resource_type=None)

Bases: object

Pagination cursor for continuing a billing activity query.

Parameters:

search_after (datetime | None)
search_after_resource_id (str | None)
search_after_resource_type (str | None)

search_after: Only include entries strictly after this time.

search_after_resource_id: Resource ID of the last entry from the previous page. Required alongside search_after to break ties between resources sharing the same time.

search_after_resource_type: Resource type of the last entry from the previous page. Required alongside search_after to break ties between resources sharing the same time.

class lightning_sdk.ActivityFileFormat(*values)

Bases: str, Enum

File format to return a billing activity report in.

class lightning_sdk.BillingActivity(total_cost=None, total_saved_cost=None, usage=<factory>, daily_usage=<factory>, has_more=False, search_after=None, search_after_resource_id=None, search_after_resource_type=None)

Bases: object

Billing activity for an org/teamspace scope, as returned by the V2 usage report endpoint.

Parameters:

total_cost (float | None)
total_saved_cost (float | None)
usage (List[BillingResourceUsage])
daily_usage (List[BillingDailyUsage])
has_more (bool)
search_after (datetime | None)
search_after_resource_id (str | None)
search_after_resource_type (str | None)

total_cost: Total credits spent by all filtered resources during the queried time range.

total_saved_cost: Total credits saved by all filtered resources during the queried time range.

usage: Per-resource usage/cost, one entry per filtered resource.

daily_usage: Usage/cost aggregated by day.

has_more: Whether more entries are available past limit. If True, pass a BillingActivityCursor built from search_after, search_after_resource_id, and search_after_resource_type to fetch the next page.

search_after: Cursor value to continue pagination from. Only set when limit was provided on the request.

search_after_resource_id: Paired with search_after to break ties between resources sharing the same search_after time.

search_after_resource_type: Paired with search_after to break ties between resources sharing the same search_after time.

class lightning_sdk.BillingActivityFilterValues(project_ids=<factory>, resource_ids=<factory>, resource_ids_truncated=False, resource_types=<factory>, user_ids=<factory>)

Bases: object

The set of values a billing activity query can be filtered by, for a given scope.

Parameters:

project_ids (List[str])
resource_ids (List[BillingNamedFilterValue])
resource_ids_truncated (bool)
resource_types (List[str])
user_ids (List[str])

project_ids: Teamspace (project) IDs with billing activity in the queried scope.

resource_ids: Resource IDs with billing activity in the queried scope, paired with their display names.

resource_ids_truncated: Whether resource_ids was truncated due to too many results.

resource_types: Resource types with billing activity in the queried scope.

user_ids: User IDs with billing activity in the queried scope.

class lightning_sdk.BillingResourceUsage(id=None, user_id=None, project_id=None, cluster_id=None, resource_type=None, resource_name=None, created_at=None, deleted_at=None, billed_time_seconds=None, cost=None, saved_cost=None, bucket_start=None)

Bases: object

A single resource’s usage/cost within a billing activity report.

Parameters:

id (str | None)
user_id (str | None)
project_id (str | None)
cluster_id (str | None)
resource_type (str | None)
resource_name (str | None)
created_at (datetime | None)
deleted_at (datetime | None)
billed_time_seconds (int | None)
cost (float | None)
saved_cost (float | None)
bucket_start (datetime | None)

id: ID of the resource.

user_id: ID of the user that owns/started the resource.

project_id: ID of the teamspace (project) the resource belongs to.

cluster_id: ID of the cloud account the resource ran on.

resource_type: Type of the resource (e.g. “Studio”, “Job”).

resource_name: Name of the resource.

created_at: When the resource was created.

deleted_at: When the resource was deleted, if it has been.

billed_time_seconds: Total billed time for this resource, in seconds.

cost: Total credits spent by this resource.

saved_cost: Total credits saved by this resource.

bucket_start: Start of the usage rollup bucket this row represents.

class lightning_sdk.BillingDailyUsage(day=None, total_cost=None, total_saved_cost=None, total_prompt_tokens=None, total_completion_tokens=None, total_num_messages=None)

Bases: object

Aggregated usage/cost for a single day within a billing activity report.

Parameters:

day (datetime | None)
total_cost (float | None)
total_saved_cost (float | None)
total_prompt_tokens (int | None)
total_completion_tokens (int | None)
total_num_messages (int | None)

day: The day this entry aggregates.

total_cost: Total credits spent on this day.

total_saved_cost: Total credits saved on this day.

total_prompt_tokens: Total prompt tokens consumed on this day.

total_completion_tokens: Total completion tokens consumed on this day.

total_num_messages: Total number of messages sent on this day.

class lightning_sdk.BillingNamedFilterValue(id=None, name=None)

Bases: object

A filterable resource ID paired with its display name.

Parameters:

id (str | None)
name (str | None)

id: ID of the resource.

name: Display name of the resource.

Was this page helpful?