Periodic fleet traffic and native usage summaries#

PropertyValue
Servicecrossfire
OperationfleetStatistics
MethodGET
Path/api/fleets/{fleetId}/statistics
Authenticationhuman
Success status200
Response dataUnpaginated value
Request formatjson
Maximum request body2097152 bytes (service default)
Permission codesagent.read.owned, agent.read.any

Listed permission codes are alternatives, not token scopes. The service also checks access to the requested records and rejects stale revisions or controller generations.

Path parameters#

object; fields below; unknown fields rejected

Field pathRepresentation and constraints
fleetIdlowercase opaque UUID

Validation#

check.object({ fleetId: check.identifier })

Referenced definitions:

Query parameters#

custom validation: statisticsQuery ; see function below

Accepted query parameters: hours, page, pageSize.

Query parameters are URL text. The validation function below specifies their format, defaults and combinations. Pagination applies only to operations that use it.

Additional checks#

The following checks apply in addition to the field limits.

Constraint on value:

export function statisticsQuery(input: unknown) {
    if (!(input instanceof URLSearchParams) || [...input.keys()].some(key => !['hours', 'page', 'pageSize'].includes(key) || input.getAll(key).length !== 1))
        return failure('invalid', 'Unknown or duplicated statistics query');
    if (['hours', 'page', 'pageSize'].some(key => input.has(key) && !/^[1-9][0-9]*$/u.test(input.get(key)!)))
        return failure('invalid', 'Statistics query values must be canonical positive integers');
    const hours = Number(input.get('hours') ?? 24), page = Number(input.get('page') ?? 1), pageSize = Number(input.get('pageSize') ?? 20);
    return [1, 24, 168, 720].includes(hours) && Number.isSafeInteger(page) && page >= 1 && page <= 100000 && Number.isSafeInteger(pageSize) && pageSize >= 1 && pageSize <= 100
        ? success({ hours, page, pageSize }) : failure('invalid', 'Select 1, 24, 168 or 720 hours and valid pagination');
}

Validation#

statisticsQuery

Referenced definitions:

Request body#

empty object; unknown fields rejected

Validation#

check.empty

Referenced definitions:

Response data#

object; fields below; unknown fields rejected ( fleetStatistics )

Field pathRepresentation and constraints
capturedAtexact JSON integer; 0…9007199254740991 ( count )
sinceexact JSON integer; 0…9007199254740991 ( count )
retentionDaysexact JSON integer; 0…9007199254740991 ( count )
intervalsexact JSON integer; 0…9007199254740991 ( count )
droppedexact JSON integer; 0…9007199254740991 ( count )
firstReportAtexact JSON integer; 0…9007199254740991 ( count ); JSON null permitted
lastReportAtexact JSON integer; 0…9007199254740991 ( count ); JSON null permitted
totalsobject; fields below; unknown fields rejected ( totals )
totals.observedexact JSON integer; 0…9007199254740991 ( count )
totals.deliveredexact JSON integer; 0…9007199254740991 ( count )
totals.contentBytesexact JSON integer; 0…9007199254740991 ( count )
totals.deliveredBytesexact JSON integer; 0…9007199254740991 ( count )
totals.attachmentBytesexact JSON integer; 0…9007199254740991 ( count )
totals.largestBytesexact JSON integer; 0…9007199254740991 ( count )
agentsarray; 0–100 entries; item: object; fields below; unknown fields rejected
agents[].agentIdlowercase opaque UUID
agents[].displayNamestring; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls
agents[].matrixUserIdwell-formed Matrix user ID; maximum 255 UTF-16 units
agents[].totalsobject; fields below; unknown fields rejected ( totals )
agents[].totals.observedexact JSON integer; 0…9007199254740991 ( count )
agents[].totals.deliveredexact JSON integer; 0…9007199254740991 ( count )
agents[].totals.contentBytesexact JSON integer; 0…9007199254740991 ( count )
agents[].totals.deliveredBytesexact JSON integer; 0…9007199254740991 ( count )
agents[].totals.attachmentBytesexact JSON integer; 0…9007199254740991 ( count )
agents[].totals.largestBytesexact JSON integer; 0…9007199254740991 ( count )
agents[].tokensobject; fields below; unknown fields rejected; constraint: Token subsets exceed their parent counts ( tokenCounts ); JSON null permitted
agents[].tokens.inputexact JSON integer; 0…9007199254740991 ( count )
agents[].tokens.cachedInputexact JSON integer; 0…9007199254740991 ( count )
agents[].tokens.cacheWriteInputexact JSON integer; 0…9007199254740991 ( count ); JSON null permitted
agents[].tokens.outputexact JSON integer; 0…9007199254740991 ( count )
agents[].tokens.reasoningOutputexact JSON integer; 0…9007199254740991 ( count ); JSON null permitted
agents[].tokens.totalexact JSON integer; 0…9007199254740991 ( count )
flowsarray; 0–100 entries; item: object; fields below; unknown fields rejected
flows[].agentIdlowercase opaque UUID
flows[].senderMatrixIdwell-formed Matrix user ID; maximum 255 UTF-16 units
flows[].senderNamestring; 1–255 UTF-16 units; well-formed Unicode; no C0/DEL controls; JSON null permitted
flows[].roomIdimmutable Matrix room ID; maximum 255 UTF-16 units
flows[].messageTypestring; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls
flows[].totalsobject; fields below; unknown fields rejected ( totals )
flows[].totals.observedexact JSON integer; 0…9007199254740991 ( count )
flows[].totals.deliveredexact JSON integer; 0…9007199254740991 ( count )
flows[].totals.contentBytesexact JSON integer; 0…9007199254740991 ( count )
flows[].totals.deliveredBytesexact JSON integer; 0…9007199254740991 ( count )
flows[].totals.attachmentBytesexact JSON integer; 0…9007199254740991 ( count )
flows[].totals.largestBytesexact JSON integer; 0…9007199254740991 ( count )
metaobject; fields below; unknown fields rejected
meta.pageexact JSON integer; 0…9007199254740991 ( count )
meta.pageSizeexact JSON integer; 0…9007199254740991 ( count )
meta.totalItemsexact JSON integer; 0…9007199254740991 ( count )
meta.totalPagesexact JSON integer; 0…9007199254740991 ( count )
tokensobject; fields below; unknown fields rejected; constraint: Token subsets exceed their parent counts ( tokenCounts ); JSON null permitted
tokens.inputexact JSON integer; 0…9007199254740991 ( count )
tokens.cachedInputexact JSON integer; 0…9007199254740991 ( count )
tokens.cacheWriteInputexact JSON integer; 0…9007199254740991 ( count ); JSON null permitted
tokens.outputexact JSON integer; 0…9007199254740991 ( count )
tokens.reasoningOutputexact JSON integer; 0…9007199254740991 ( count ); JSON null permitted
tokens.totalexact JSON integer; 0…9007199254740991 ( count )
spendstring; 1–100 UTF-16 units; well-formed Unicode; no C0/DEL controls; JSON null permitted

Additional checks#

The following checks apply in addition to the field limits.

Constraint on tokens:

value => value.cachedInput <= value.input && (value.cacheWriteInput ?? 0) <= value.input
    && (value.reasoningOutput ?? 0) <= value.output

Validation#

fleetStatistics

Referenced definitions:

Response envelope#

A successful JSON response contains data and meta. Replace the data placeholder below with the response fields described above. Errors contain error instead of data.

{
  "data": "<value matching the response-data validator>",
  "meta": {
    "requestId": "00000000-0000-0000-0000-000000000001"
  }
}