Working with Timestamps

The Katalys API returns and accepts timestamps as epoch-milliseconds. An epoch is a computing value that represents a date+time as seconds or milliseconds from 1970-01-01 00:00:00Z (more info on Wikipedia).

Epoch-millisecond timestamps are used in:

• Statistics Reporting, to filter the results.

• Statistics results, such as day-parting or date breakdowns.

• Conversions Reporting, to filter the results.

• Conversion Report result fields, such as Order Time or Time of Click.

Timestamp ranges for the Katalys API are inclusive, meaning that timestamp ranges should be from 00:00:00 to 23:59:59 of your selected date range to include only the data you wish to return. For convenience, the Katalys API filters accept epoch-seconds or epoch-milliseconds when defining filters. Reporting overall is only accurate down to the second, so there is no difference when using second-resolution 23:59:59 or millisecond-resolution 23:59:59.999.

Example Code

Converting a date-time into epoch-milliseconds is easy with most languages. Below is an example in JavaScript using the Moment library.

const moment = require('moment-timezone');
const mTime = moment().tz("America/Los_Angeles").startOf('day').valueOf();
// define timestamp range for "Previous 7 Days"
const startTime = mTime - (7 * 24 * 60 * 60 * 1000);
const endTime = mTime - 1; // date-range is inclusive, so must exclude 00:00 of next day

Converting a timestamp into a date/time in your local timezone is easy.

for (const reportRow of reportFromKatalysApi) {
  const { orderTime } = reportRow;
  const localTime = new Date(orderTime);
  console.log("Time of order:", localTime);
}

Matching KMP Portal

You can see the KMP portal’s filters in the query-string when you run a report. Review the following example:

https://app.katalys.com/pub/xxx-xxxx-xxxxxxxxxxx/conversions?dims=order_time,order_id,conversion_status,offer,aff,payout,click_time&filters=status!1,9|time!1748761200000,1748847599999!range

The values 1748761200000,1748847599999 are the start and end times in epoch-milliseconds shown in the portal’s view.

Daylight Savings Time

The reporting portal by default uses the US/Los_Angeles timezone (also called “Pacific Time”). This timezone has a daylight savings time adjustment during the months March thru November. Epoch times have no such adjustment, so the KMP portal handles this by changing the passed epoch-milliseconds into the API to match user expectations.