Stats Mix

Our API can be easily accessed using the StatsMix Java Library.

You must have an API key to use the API. You can find it in the API section under "My Account" in StatsMix. If you don't have an account, sign up for a free Developer account here.

Once you have your API key, you can get started.


Download the jar file and it's dependancies. Include these in your build path.

Links to all the depedencies if you need to resolve version errors:


Create a new StatsMix client with your API Key:

import com.statsmix.*;
Client smClient = new Client("YOUR_API_KEY")

Using StatsMix to Track Events

Any time you want to track an event in your app, simply call:

smClient.track("Metric Name", properties, meta_data)

Which returns the XML response as a string.

If a metric with that name doesn't exist in your account, one will be created automatically. If the profile isn't set, the metric will use the first profile_id created in your account. (Developer, Basic, and Standard plans only have one profile.)


Track every time a new blog post is created:

//create a stat with the value 1 (default) for the metric called "Blog Posts"
smClient.track("Blog Posts")

Count the number of new user accounts in the last 24 hours

int count = //generate the number of new users 
smClient.track("Daily New Users", count)

Additional Options

If you’d like to change the timestamp of a stat, pass in the parameter generated_at, which is a datetime value. Any datetime value is stored in the database as UTC. For daily email reports and charting on the StatsMix site, we convert from UTC to the user's timezone, which can be configured in the Account Settings section of StatsMix.

List<NameValuePair> properties = new ArrayList<NameValuePair>(2);
DateFormat dateFormat = new SimpleDateFormat("yyyy/MM/dd HH:mm:ss");
Date date = new Date();
string gen_at = dateFormat.format(date);
properties.add(new BasicNameValuePair("generated_at", gen_at);
smClient.track("Metric Name", properties);

Higher level StatsMix accounts can have additional profiles. A profile can be described as a grouping or "bucket" of metrics. For example, an agency may want to create a profile for each customer.

If you are tracking metrics with the same name in two different profiles, you must specify which profile to use with profile_id. (If you don't specify profile_id, StatsMix will default to the first profile in your account.)

properties.add(new BasicNameValuePair("profile_id", "789"));
smClient.track("Blog Posts", properties)

You can find the profile ID in StatsMix by creating a metric and looking at the API Details under Code Snippets in the Data & API section. (It will also be in the URL as /profiles/123/metrics/456 - in this case the profile id is 123.)

Adding Metadata

You optionally can "tag" your data with metadata in the meta option. For example, if you have a file upload utility and want to track what kinds of files you are receiving:

// a user just uploaded a PDF file; track the type of file using metadata
JSONObject meta = new JSONObject();
meta.put("file type", "PDF");
smClient.track("Metric Name", properties, meta);

You can include multiple key-value pairs in the same stat:

meta.put("file type", "PDF");
meta.put("size", "1 mb");
meta.put("country of origin", "Absurdistan");
smClient.track("Metric Name", properties, meta);

Adding Your Own Identifier

If you need the ability to update a stat after the fact, you can pass in a unique identifier ref_id as one of the properties (scoped to that metric).

For example, perhaps you want to update the number of users every hour instead of every day. If you pass in the date as ref_id, StatsMix will check whether a stat with that ref_id already exists for that metric. If found, StatsMix will update instead of inserting. ref_id can be any string you like. In the example below, we use the date we generated earlier.

properties.add(new BasicNameValuePair("ref_id", gen_at);
smClient.track("Blog Posts", properties)


If you hit a plan level limit (i.e. you go over the number of API requests available to your account), the API will return a 403 Forbidden error and an explanation.

The number of API requests and profiles you can create is based on the type of account you have. For example, Standard plans are limited to 300,000 API requests per month. You can see the current options on our pricing page.