Usage files

Represents a file containing usage events that has been uploaded for processing.

Upload usage events using files

Follow these steps to upload usage event files:

Step 1: Request an usage_file object using the upload endpoint. This returns an url.

Step 2: Create a CSV file containing the usage event records. Ensure that the file meets the expected format and complies with the file upload constraints. Only text/csv files are supported.

Step 3: Upload the CSV file using the returned url.
Make an HTTP PUT request to the upload URL. Include the file in the request body as binary data (raw file content).

Step 4: Check the uploaded usage_file_status using the retrieve_file_processing_status endpoint.

Best practices

• We recommend not to create empty files which contain only header rows.
• We recommend uploading files in batches of 100,000 events per file or lesser to ensure optimal performance.
• We recommend ensuring that no row contains extra columns without corresponding headers.

File upload constraints

• File names should not contain any special characters except for underscores _ and hyphens -.
• File names must be under 150 characters and include the appropriate extensions, such as .csv.
• The supported delimiter for CSV file format is comma(,).
• The file must not exceed 1 GB size or 1 million records. The lesser of the two limits applies.
• The uploaded data will be processed at the rate of 10,000 events per minute.

File field constraints

• Make sure your file follows the sample file format:

• Learn more about deduplication_id, subscription_id, and usage_timestamp.

• Each row must include deduplication_id, subscription_id, and usage_timestamp. Rows missing any of these fields are flagged as failed events.

• Any top-level fields in the event row that are not a recognized field (deduplication_id, subscription_id, and usage_timestamp) will automatically be added to the properties.

  Field Naming Guidelines: Ensure that your file's column headers follow the required naming rules to avoid processing issues:

  • Start with: a lowercase letter (a-z)

• May include:

  • Lowercase letters (a-z)
  • Numbers (0-9)
  • Underscores (_)

Validating and handling errors

When uploading a usage events file using the API, certain validation checks are performed. If issues are detected, the upload or processing may fail. The following sections explain the possible error scenarios and how they are handled.