Skip to main content
POST
/
usage
Create a usage event
curl --request POST \
  --url https://api-dev.narrative.io/usage \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "company_id": 1,
  "dimensions": {
    "dataset_id": "123"
  },
  "event_timestamp": "2022-11-10T00:00:00Z",
  "event_type": "processing-dataset-ingestion",
  "idempotency_key": "882e0a91-10a2-47c7-8e70-69344d725a6f",
  "sku": "general-purpose-processing-aws-us-east-1",
  "usage": {
    "unit": "gigabytes",
    "value": 181.281
  },
  "created_by": 2,
  "measures": {
    "rows": 8212837
  }
}
'
{
  "id": "fe0212f6-3440-44e6-b049-ef6c5ad1f396",
  "app_id": 5,
  "company_id": 1,
  "created_at": "2022-11-10T00:00:00Z",
  "dimensions": {
    "dataset_id": "123"
  },
  "event_timestamp": "2022-11-10T00:00:00Z",
  "event_type": "processing-dataset-ingestion",
  "idempotency_key": "882e0a91-10a2-47c7-8e70-69344d725a6f",
  "sku": "general-purpose-processing-aws-us-east-1",
  "usage": {
    "unit": "gigabytes",
    "value": 181.281
  },
  "created_by": 2,
  "measures": {
    "rows": 8212837
  }
}

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
company_id
integer
required

The ID of the company to which the usage will be applied.

Example:

1

​
dimensions
object
required

An arbitrary collection of key-value pairs that can be used to categorize or tag the event.

These key-values become aggregable dimensions in usage reports.

Example:
{ "dataset_id": "123" }
​
event_timestamp
string<date-time>
required

ISO-8601 timestamp indicating when the usage event occurred. Cannot be more than 72 hours in the past.

Example:

"2022-11-10T00:00:00Z"

​
event_type
string
required

The type of usage event. event_type works alongside dimensions and measures to describe the details of the event.

Example:

"processing-dataset-ingestion"

​
idempotency_key
string<uuid>
required

A UUID that ensures the usage event is processed and stored only once, even if the event is sent multiple times.

This unique identifier helps to prevent duplicate usage events from being recorded and allows for reliable processing and storage of the event. If a usage event with a previously used idempotency_key is received, the original stored event is returned instead of creating a new event.

Example:

"882e0a91-10a2-47c7-8e70-69344d725a6f"

​
sku
string
required

Unique identifier for the product for .

Example:

"general-purpose-processing-aws-us-east-1"

​
usage
object
required

The amount of the product referred to by the sku that is being used, expressed as a numerical value and corresponding unit of measure.

The unit field must match the unit of measure for the product, and the value field indicates the amount of the product used in terms of the given unit.

​
created_by
integer

Optional. The ID of the user that triggered the usage event.

Example:

2

​
measures
object

A set of additional numerical values associated with the usage event that are beyond what is captured in the usage field. These values may be used for reporting purposes and can provide additional context about the event.

Example:
{ "rows": 8212837 }

Response

200 - application/json

OK

​
id
string<uuid>
required

Unique identifier for the usage event.

Example:

"fe0212f6-3440-44e6-b049-ef6c5ad1f396"

​
app_id
integer
required

The id of the application that created the usage event.

Example:

5

​
company_id
integer
required

The ID of the company to which the usage will be applied.

Example:

1

​
created_at
string<date-time>
required

ISO-8601 timestamp indicating when the usage event was persisted.

Example:

"2022-11-10T00:00:00Z"

​
dimensions
object
required

An arbitrary collection of key-value pairs that can be used to categorize or tag the event.

These key-values become aggregable dimensions in usage reports.

Example:
{ "dataset_id": "123" }
​
event_timestamp
string<date-time>
required

ISO-8601 timestamp indicating when the usage event occurred. Cannot be more than 72 hours in the past.

Example:

"2022-11-10T00:00:00Z"

​
event_type
string
required

The type of usage event. event_type works alongside dimensions and measures to describe the details of the event.

Example:

"processing-dataset-ingestion"

​
idempotency_key
string<uuid>
required

A UUID that ensures the usage event is processed and stored only once, even if the event is sent multiple times.

This unique identifier helps to prevent duplicate usage events from being recorded and allows for reliable processing and storage of the event. If a usage event with a previously used idempotency_key is received, the original stored event is returned instead of creating a new event.

Example:

"882e0a91-10a2-47c7-8e70-69344d725a6f"

​
sku
string
required

Unique identifier for the product for .

Example:

"general-purpose-processing-aws-us-east-1"

​
usage
object
required

The amount of the product referred to by the sku that is being used, expressed as a numerical value and corresponding unit of measure.

The unit field must match the unit of measure for the product, and the value field indicates the amount of the product used in terms of the given unit.

​
created_by
integer

Optional. The ID of the user that triggered the usage event.

Example:

2

​
measures
object

A set of additional numerical values associated with the usage event that are beyond what is captured in the usage field. These values may be used for reporting purposes and can provide additional context about the event.

Example:
{ "rows": 8212837 }