Get‑ShpUsage

SYNOPSIS

Returns the per-session usage log of prompts, tokens, cost, and credits.

SYNTAX

Get-ShpUsage [-Summary] [[-Since] <DateTime>] [[-Before] <DateTime>] 
 [<CommonParameters>]

DESCRIPTION

Reads the module-scoped usage log that Invoke-Shp appends to on every call: one record per prompt capturing the timestamp, the model used, the prompt text, prompt and completion token counts, the peak single-request context-window occupancy (ContextTokens), the estimated USD cost and credit count, the number of tool-calling iterations and tool calls, the finish reason and the wall-clock duration. Use it to analyse how many tokens and credits a PowerShell session has spent. With -Summary it returns a single aggregate object (totals plus a per-model breakdown) instead of the individual records. The log is scoped to the current PowerShell session and is not persisted to disk; reset it with Clear-ShpUsage.

Bounded requests whose Usage is unknown retain null aggregate tokens and cost. Their summaries include UnknownUsageCalls and KnownUsage, preserving reported partial values without describing them as totals.

A call that FAILED is recorded too, with Success false and the failure message on Error, carrying whatever spend its completed round-trips had already incurred. That matters twice: a run's success rate would otherwise be 100% by construction, because only successes were in the log at all; and a Turn is a loop of billable round-trips, so a turn refused on its third round-trip really was charged for the first two. Only a call that reached the API is recorded - a parameter combination rejected before any request was never a call.

EXAMPLES

EXAMPLE 1

Get-ShpUsage

Lists every recorded call in the current session with its tokens, cost, and credits.

EXAMPLE 2

Get-ShpUsage -Summary

Shows the session totals (attempted, succeeded and failed calls, tokens, cost, credits, duration and time span) and a per-model breakdown.

EXAMPLE 3

Get-ShpUsage | Where-Object { -not $_.Success } | Select-Object Timestamp, Model, Error

Lists the calls that failed. A failed call is recorded like any other, so it can be inspected rather than merely being absent.

EXAMPLE 4

$start = [datetime]::UtcNow
Get-ShpUsage -Summary -Since $start

Summarises a single phase of a longer run without resetting the log.

EXAMPLE 5

Get-ShpUsage | Group-Object FinishReason | Select-Object Name, Count

Groups the records by any key. There is deliberately no -GroupBy parameter: the records are returned, so Group-Object already does this for every field. ByModel is pre-aggregated only because the per-model split is the common case.

PARAMETERS

-Before

Only consider calls recorded at or before this time (UTC).

Type: DateTime
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Since

Only consider calls recorded at or after this time (UTC). Applies to the records and to -Summary, so one phase of a run can be summarised without clearing the log between phases.

Type: DateTime
Parameter Sets: (All)
Aliases:

Required: False
Position: 1
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-Summary

Return one aggregate object - attempted, succeeded and failed call counts, prompt/completion/total tokens, the peak context-window occupancy (ContextTokens, a maximum rather than a sum), total cost in USD, total credits, total and mean duration, the time span covered, and a per-model breakdown - instead of the individual per-call records.

Note that Calls counts calls ATTEMPTED. Read Succeeded for the number that returned an answer. ElapsedMs is wall-clock between the first and last call and is deliberately not the sum of DurationMs: under Invoke-ShpBatch the calls overlap, so the sum can far exceed the elapsed time, and the ratio between them is the speed-up the batch bought.

Type: SwitchParameter
Parameter Sets: (All)
Aliases:

Required: False
Position: Named
Default value: False
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.Management.Automation.PSCustomObject

The per-call usage records, or - with -Summary - a single aggregate

object with a ByModel breakdown.

NOTES

RELATED LINKS

Clear-ShpUsage

Invoke-Shp