Macrometa Usage API
The Usage API from Macrometa — 5 operation(s) for usage.
OpenAPI Specification
openapi: 3.0.0
info:
title: Macrometa API Reference Activity Metrics Usage API
version: 0.17.17
description: API reference for the Macrometa Global Data Network.
license:
name: Macrometa License, Version 2.0
servers:
- url: https://api-play.paas.macrometa.io
description: GDN API
host: api-play.paas.macrometa.io
security:
- ApiKeyAuth: []
- BearerAuth: []
tags:
- name: Usage
paths:
/api/prerender/v1/usage/{aggregationType}:
get:
summary: Get usage metrics
tags:
- Usage
description: Returns usage metrics for a specified time range, with mandatory aggregation by type and an optional origin filter. This endpoint requires from and to query parameters as epoch times, along with an aggregationType in the path to define the data aggregation granularity (e.g., hourly, daily, monthly). It supports pagination (limit, offset) and sorting (sortOrder, sortBy) options in the query. Authentication is managed via the customerId header.
parameters:
- schema:
type: number
in: query
name: from
required: true
description: Timestamp (in seconds) used as the initial time for filtering.
- schema:
type: number
in: query
name: to
required: true
description: Timestamp (in seconds) used as the final time for filtering.
- schema:
type: number
minimum: 1
default: 1000
maximum: 1000
in: query
name: limit
required: false
description: Limit for results.
- schema:
type: number
default: 0
in: query
name: offset
required: false
description: Offset for results.
- schema:
type: string
enum:
- ASC
- DESC
default: ASC
in: query
name: sortOrder
required: false
description: Sorting order.
- schema:
type: string
enum:
- timestamp
- maxRps
- totalRenders
default: timestamp
in: query
name: sortBy
required: false
description: Sorting field.
- schema:
type: boolean
default: 'false'
in: query
name: aggregation
required: false
description: If the aggregate flag is true, then the results are consolidated and returned as an aggregate summary for the specified start and end period.
- schema:
type: string
enum:
- hourly
- daily
- monthly
in: path
name: aggregationType
required: true
description: Aggregation type.
- schema:
type: string
in: header
name: x-photoniq-customerid
required: true
description: Customer unique identifier.
responses:
'200':
description: Usage metrics fetched successfully.
content:
application/json:
schema:
type: array
description: Usage metrics fetched successfully.
items:
type: object
properties:
timestamp:
type: number
description: The time at which the event occurred, represented as a Unix timestamp.
totalRenders:
type: number
description: The total number of rendering operations performed.
origin:
type: string
format: uri
description: The URL of the origin from which the requests are initiated.
maxRps:
type: number
description: The maximum number of requests per second (RPS) processed.
example:
- timestamp: 1672628400000
totalRenders: 44
maxRps: 3
- timestamp: 1672542000000
totalRenders: 66
maxRps: 4
'400':
description: Bad request.
content:
application/json:
schema:
type: object
description: Bad request.
properties:
status:
type: string
description: Error status.
message:
type: string
description: Error message.
required:
- status
- message
example:
status: ERROR
message: Header x-photoniq-customerid is required.
'500':
description: Internal server error.
content:
application/json:
schema:
type: object
description: Internal server error.
properties:
status:
type: string
description: Error status.
message:
type: string
description: Error message.
required:
- status
- message
example:
status: ERROR
message: Internal server error.
/api/prerender/v1/usage/{aggregationType}/{origin}:
get:
summary: Get usage metrics by origin
tags:
- Usage
description: Returns usage metrics for a specified time range, with mandatory aggregation by type and an optional origin filter. This endpoint requires from and to query parameters as epoch times, along with an aggregationType in the path to define the data aggregation granularity (e.g., hourly, daily, monthly). It supports pagination (limit, offset) and sorting (sortOrder, sortBy) options in the query. Authentication is managed via the customerId header.
parameters:
- schema:
type: number
in: query
name: from
required: true
description: Timestamp (in seconds) used as the initial time for filtering.
- schema:
type: number
in: query
name: to
required: true
description: Timestamp (in seconds) used as the final time for filtering.
- schema:
type: number
minimum: 1
default: 1000
maximum: 1000
in: query
name: limit
required: false
description: Limit for results.
- schema:
type: number
default: 0
in: query
name: offset
required: false
description: Offset for results.
- schema:
type: string
enum:
- ASC
- DESC
default: ASC
in: query
name: sortOrder
required: false
description: Sorting order.
- schema:
type: string
enum:
- timestamp
- maxRps
- totalRenders
default: timestamp
in: query
name: sortBy
required: false
description: Sorting field.
- schema:
type: boolean
default: 'false'
in: query
name: aggregation
required: false
description: If the aggregate flag is true, then the results are consolidated and returned as an aggregate summary for the specified start and end period.
- schema:
type: string
enum:
- hourly
- daily
- monthly
in: path
name: aggregationType
required: true
description: Aggregation type.
- schema:
type: string
in: path
name: origin
required: true
description: Origin hostname.
- schema:
type: string
in: header
name: x-photoniq-customerid
required: true
description: Customer unique identifier.
responses:
'200':
description: Usage metrics fetched successfully.
content:
application/json:
schema:
type: array
description: Usage metrics fetched successfully.
items:
type: object
properties:
timestamp:
type: number
description: The time at which the event occurred, represented as a Unix timestamp.
totalRenders:
type: number
description: The total number of rendering operations performed.
origin:
type: string
format: uri
description: The URL of the origin from which the requests are initiated.
maxRps:
type: number
description: The maximum number of requests per second (RPS) processed.
example:
- timestamp: 1672628400000
totalRenders: 44
maxRps: 3
- timestamp: 1672542000000
totalRenders: 66
maxRps: 4
'400':
description: Bad request.
content:
application/json:
schema:
type: object
description: Bad request.
properties:
status:
type: string
description: Error status.
message:
type: string
description: Error message.
required:
- status
- message
example:
status: ERROR
message: Header x-photoniq-customerid is required.
'500':
description: Internal server error.
content:
application/json:
schema:
type: object
description: Internal server error.
properties:
status:
type: string
description: Error status.
message:
type: string
description: Error message.
required:
- status
- message
example:
status: ERROR
message: Internal server error.
/api/vwr/v1/usage/hourly:
get:
summary: Gets hourly usage statistics
tags:
- Usage
description: Get hourly usage statistics of a specific waiting room for a specified time period.
operationId: getHourlyUsage
security:
- APIKeyAuth: []
parameters:
- name: waitingroom
in: query
required: true
description: Unique identifier for a waiting room.
schema:
type: string
- name: start
in: query
required: true
description: The start date and time used for querying usage data. Must be provided in RFC3339 date-time format and be in UTC.
schema:
type: string
example: YYYY-MM-DDTHH:MM:SSZ
- name: end
in: query
required: true
description: The end date and time used for querying usage data. Must be provided in RFC3339 date-time format and be in UTC.
schema:
type: string
example: YYYY-MM-DDTHH:MM:SSZ
- name: aggregate
in: query
required: false
description: If the _aggregate_ flag is _true_, then the results are consolidated and returned as an aggregate summary for the specified _start_ and _end_ period. If the _aggregate_ flag is _false_ or not provided, then the data is returned as separate, distributed records for the same period on an hourly basis without aggregation. If _aggregate_ flag is _true_, then [offset, limit, sort, order] are not considered.
schema:
type: boolean
default: false
- name: limit
in: query
required: false
description: The _limit_ parameter determines the number of usage records returned.
schema:
type: number
default: 1000
minimum: 1
maximum: 1000
- name: offset
in: query
required: false
description: Represents the starting point from where to begin fetching the usage records. This parameter is especially useful in conjunction with the _limit_ parameter for pagination of a large number of usage records. By default, it is set to 0, meaning that data retrieval will start from the very first record. For example, if you have 10,000 usage records and set the _limit_ to 100, then the first API call without an _offset_ will retrieve records 1 to 100. If you set the _offset_ to 100 for the next call, you will retrieve records 101 to 200, and so on. This way, by incrementing the _offset_ by the _limit_ value for successive calls, you can paginate through the entire dataset.
schema:
type: number
default: 0
- name: sortby
in: query
required: false
description: The field used for sorting.
schema:
type: string
enum:
- usage_requests
- max_rps
- waitingroom_key
- timestamp
default: timestamp
- name: order
in: query
required: false
description: "The sort order:\n * _asc_ - Ascending, from A to Z\n * _desc_ - Descending, from Z to A\n"
schema:
type: string
enum:
- asc
- desc
default: asc
responses:
'200':
description: Successfully fetched usage information.
headers:
X-count:
description: The total number of records for the specified time period if _aggregate_ is set to _false_.
schema:
type: number
default: 1000
content:
application/json:
schema:
oneOf:
- type: array
items:
$ref: '#/components/schemas/UsageGetResponse'
- type: array
items:
$ref: '#/components/schemas/AggregateUsageGetResponse'
examples:
example:
summary: Response when aggregate is false.
value:
- waitingroom_key: test.waitingroom
requests: 1305
max_rps: 100
timestamp: '2023-07-12T07:00:00.000Z'
- waitingroom_key: test.waitingroom
requests: 1200
max_rps: 125
timestamp: '2023-07-12T08:00:00.000Z'
example_two:
summary: Response when aggregate is true.
value:
- waitingroom_key: test.waitingroom
requests: 2505
max_rps: 112.5
'401':
description: Authorization failure due to invalid authentication credentials.
'403':
description: Either the API key doesn't have permissions or it is deactivated.
'404':
description: Usage info not available.
'500':
description: Internal server error.
/api/vwr/v1/usage/daily:
get:
summary: Gets daily usage statistics
tags:
- Usage
description: Gets daily usage statistics of a specific waiting room for a specified time period.
operationId: getDailyUsage
security:
- APIKeyAuth: []
parameters:
- name: waitingroom
in: query
required: true
description: Unique identifier for a waiting room.
schema:
type: string
- name: start
in: query
required: true
description: The start date and time used for querying usage data. Must be provided in RFC3339 date-time format and be in UTC.
schema:
type: string
example: YYYY-MM-DDTHH:MM:SSZ
- name: end
in: query
required: true
description: The end date and time used for querying usage data. Must be provided in RFC3339 date-time format and be in UTC.
schema:
type: string
example: YYYY-MM-DDTHH:MM:SSZ
- name: aggregate
in: query
required: false
description: If the _aggregate_ flag is is included and set to _true_, then the results are consolidated and returned as an aggregate summary for the specified _start_ and _end_ period. If the _aggregate_ flag is _false_ or not provided, then the data is returned as separate, distributed records for the same period on a per-day basis without aggregation. If _aggregate_ flag is _true_, then [offset, limit, sort, order] are not considered.
schema:
type: boolean
default: false
- name: limit
in: query
required: false
description: The _limit_ parameter determines the number of usage records returned.
schema:
type: number
minimum: 1
maximum: 1000
default: 1000
- name: offset
in: query
required: false
description: Represents the starting point from where to begin fetching the usage records. This parameter is especially useful in conjunction with the _limit_ parameter for pagination of a large number of usage records. By default, it is set to 0, meaning that data retrieval will start from the very first record. For example, if you have 10,000 usage records and set the _limit_ to 100, then the first API call without an _offset_ will retrieve records 1 to 100. If you set the _offset_ to 100 for the next call, you will retrieve records 101 to 200, and so on. This way, by incrementing the _offset_ by the _limit_ value for successive calls, you can paginate through the entire dataset.
schema:
type: number
default: 0
- name: sortby
in: query
required: false
description: The field used for sorting.
schema:
type: string
enum:
- usage_requests
- max_rps
- waitingroom_key
- timestamp
default: timestamp
- name: order
in: query
required: false
description: "The sort order:\n * _asc_ - Ascending, from A to Z\n * _desc_ - Descending, from Z to A\n"
schema:
type: string
enum:
- asc
- desc
default: asc
responses:
'200':
description: Successfully fetched usage information.
headers:
X-count:
description: The total number of records for the specified time period if _aggregate_ is set to _false_.
schema:
type: number
default: 1000
content:
application/json:
schema:
oneOf:
- type: array
items:
$ref: '#/components/schemas/UsageGetResponse'
- type: array
items:
$ref: '#/components/schemas/AggregateUsageGetResponse'
examples:
example:
summary: Response when aggregate is set to false.
value:
- waitingroom_key: test.waitingroom
requests: 1305
max_rps: 100
timestamp: '2023-07-12T07:00:00.000Z'
- waitingroom_key: test.waitingroom
requests: 1200
max_rps: 125
timestamp: '2023-07-13T08:00:00.000Z'
example_two:
summary: Response when aggregate is set to true.
value:
- waitingroom_key: test.waitingroom
requests: 2505
max_rps: 112.5
'401':
description: Authorization failure due to invalid authentication credentials.
'403':
description: Either the API key doesn't have permissions or it is deactivated.
'404':
description: Usage info not available.
'500':
description: Internal server error.
/api/vwr/v1/usage/monthly:
get:
summary: Get monthly usage statistics
tags:
- Usage
description: Gets monthly usage statistics of a specific waiting room for a specified time period.
operationId: getMonthlyUsage
security:
- APIKeyAuth: []
parameters:
- name: waitingroom
in: query
required: false
description: Unique waiting room identifier. If unused, retrieve the monthly usage information for all waiting rooms.
schema:
type: string
- name: start
in: query
required: true
description: The start date and time used for querying usage data. Must be provided in RFC3339 date-time format and be in UTC.
schema:
type: string
example: YYYY-MM-DDTHH:MM:SSZ
- name: end
in: query
required: true
description: The end date and time used for querying usage data. Must be provided in RFC3339 date-time format and be in UTC.
schema:
type: string
example: YYYY-MM-DDTHH:MM:SSZ
- name: aggregate
in: query
required: false
description: If the _aggregate_ flag is included and set to _true_, then the results are consolidated and returned as an aggregate summary for the specified _start_ and _end_ period. If the _aggregate_ flag is _false_ or not provided, then the data is returned as separate, distributed records for the same period. By default, the value is false.
schema:
type: boolean
default: false
- name: limit
in: query
required: false
description: The _limit_ parameter determines the number of usage records returned.
schema:
type: number
minimum: 1
maximum: 1000
default: 1000
- name: offset
in: query
required: false
description: Represents the starting point from where to begin fetching the usage records. This parameter is especially useful in conjunction with the _limit_ parameter for pagination of a large number of usage records. By default, it is set to 0, meaning the data retrieval will start from the very first record. For example, if you have 10,000 usage records and set the _limit_ to 100, then the first API call without an _offset_ will retrieve records 1 to 100. If you set the _offset_ to 100 for the next call, you will retrieve records from 101 to 200, and so on. This way, by incrementing the _offset_ by the _limit_ value for successive calls, you can paginate through the entire dataset.
schema:
type: number
default: 0
- name: sortby
in: query
required: false
description: The field used for sorting.
schema:
type: string
enum:
- usage_requests
- max_rps
- waitingroom_key
- timestamp
default: timestamp
- name: order
in: query
required: false
description: "The sort order:\n * _asc_ - Ascending, from A to Z\n * _desc_ - Descending, from Z to A\n"
schema:
type: string
enum:
- asc
- desc
default: asc
responses:
'200':
description: Successfully fetched usage information.
headers:
X-count:
description: The total number of records for the specified time period.
schema:
type: number
default: 1000
content:
application/json:
schema:
oneOf:
- type: array
items:
$ref: '#/components/schemas/UsageGetResponse'
- type: array
items:
$ref: '#/components/schemas/AggregateUsageGetResponse'
examples:
example:
summary: Response when aggregate is false.
value:
- waitingroom_key: test.waitingroom
requests: 1305
max_rps: 100
timestamp: '2023-06-12T00:00:00.000Z'
- waitingroom_key: test.waitingroom
requests: 1200
max_rps: 125
timestamp: '2023-07-12T00:00:00.000Z'
example_two:
summary: Response when aggregate is true.
value:
- waitingroom_key: test.waitingroom
requests: 2505
max_rps: 112.5
'401':
description: Authorization failure due to invalid authentication credentials.
'403':
description: Either the API key doesn't have permissions or it is deactivated.
'404':
description: Usage info not available.
'500':
description: Internal server error.
components:
schemas:
AggregateUsageGetResponse:
type: object
properties:
waitingroom_key:
type: string
description: A unique identifier for the waiting room.
requests:
type: number
format: number
description: Total REST API requests for the specified time period.
max_rps:
type: string
description: Maximum request per second for the specified time period.
UsageGetResponse:
type: object
properties:
waitingroom_key:
type: string
description: A unique identifier for the waiting room.
requests:
type: number
format: number
description: Total REST API requests for the received time period slot.
max_rps:
type: number
format: number
description: Maximum request per second for the received time period slot.
timestamp:
type: number
description: Unix timestamp, in milliseconds, of the usage bucket.
example: 1694757100000
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: 'Provide an API Key to the `Authorization` header, prefixed with "apikey".
Example: `Authorization: apikey <key>`'
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: 'Provide a JSON Web Token (JWT) to the `Authorization` header, prefixed with "bearer".
Example: `Authorization: bearer <jwt>`'