B

API Documentation

Introduction

StatsMix provides an API that can be used to create, retrieve, update, and delete metrics and stats resources. The API is built using RESTful principles.

XML and JSON are supported as responses to API calls.


Version

The current version is 2.0. The previous version of the API (1.0) is still available, but has been deprecated.


Authentication

Authentication is currently by API key. This can be sent in the header or as a parameter. You can find your API key under 'My Account' after signing into StatsMix. To get an API key, you can sign up for a free Developer account here.


Datetime Information

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.


Response Codes

We return the following response codes:

Response Code Description
200 Success Everything went fine.
401 Unauthorized Missing or incorrect API Key.
403 Forbidden You tried to access something you did not have permissions for.
422 Unprocessable Entity You tried to create or update an object with invalid data.
404 Not Found You tried to access an object that does not exist in your account.
500 Internal Server Error Oops. Something went wrong on our end. Don't worry, we're on the case!

Limitations

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.


Resources

There are currently three resources available in the StatsMix API:


Track

URI: api.statsmix.com/api/v2/track

Track is a special endpoint that covers the most common use case: push data into a metric. It combines the functions Stat::Create and Metric::Create (if necessary) into a single method call.

Property Type Description
name string The name of the metric you are tracking. If a metric with that name does not exist in your account, one will be created automatically.
value decimal (11,2) The numeric value of the stat with a decimal precision of two. Decimal (up to 11 digits on the left side of the decimal point, two on the right).
generated_at datetime Datetime for the stat. If not set, defaults to the current timestamp. This is the datetime to be used in the charts.
meta text Metadata in JSON format about anything associated with the stat. Invalid JSON will result in a 422 error.
ref_id integer Optional reference id for a stat. If a stat already exists for the named metric and the given ref_id, the value (and optionally generated_at and meta) will be updated instead of created.
profile_id integer The unique id of the profile this stat belongs to. If not set, the metric will use the first profile_id created in your account. (Developer, Basic, and Standard plans only have one profile.)

Click here to see code samples.


Metrics

URI: api.statsmix.com/api/v2/metrics

Metrics are anything you want to measure or track. Each metric has many stats and belongs to a profile.

Property Type Description
id integer Read only. This is a system generated integer that uniquely identifies this metric.
name string The name of the metric. Metric names must be unique within a profile.
profile_id integer The profile the metric belongs in. Developer and Basic plans only have one profile, but higher plan levels can have multiple profiles to group metrics together.
sharing string Sharing status for the metric. Either "public" (unauthenticated users can view the metric at the specific URL) or "none" (default).
include_in_email 1 or 0 (boolean) This specifies whether to include the metric in the daily StatsMix email sent to users. The default is 1 (true).
url string Read only. Publicly accessible URL for the metric (only if sharing is set to "public").
created_at datetime Read only. The datetime that the metric was created.
updated_at datetime Read only. The datetime that the metric was last updated

Click here to see code samples.


Stats

URI: api.statsmix.com/api/v2/stats

Stats are individual data points that can also contain descriptive metadata. A stat belongs to a metric.

Property Type Description
id integer Read only. This is a system generated integer that uniquely identifies this stat.
value decimal (11,2) The numeric stat with a decimal precision of two. Decimal (up to 11 digits on the left side of the decimal point, two on the right)
meta string Metadata in JSON about anything associated with the stat. Invalid JSON will result in a 422 error.
ref_id string Optional reference id that you can use for updating a stat instead of the id.
profile_id integer The unique id of the profile this stat belongs to.
metric_id integer The unique id of the metric this stat belongs to.
generated_at datetime The datetime that specifically references the stat. This is used for all charting and analysis. Must be in UTC.
created_at datetime Read only. The datetime that this resource was created.
updated_at datetime Read only. The datetime that this resource was last updated

Click here to see code samples.


Code Samples

In the following examples, user variables are indicated by uppercase (ex. API_KEY). Datetime values should be specified in the following format: YYYY-MM-DD (ex. 2010-02-22 00:00:00).


Curl Command Line

Curl is the quickest way to try the StatsMix API. Full documentation on curl can be found here.


Track Example

This example posts to a metric called "My First Metric." Since no value is passed, the default of 1 is returned.

curl -H "X-StatsMix-Token: API_KEY" -d "name=My%20First%20Metric" api.statsmix.com/api/v2/track

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<stat>
  <id>2933452</id>
  <value>1.0</value>
  <meta></meta>
  <profile_id>448</profile_id>
  <metric_id>124</metric_id>
  <ref_id></ref_id>
  <generated_at>2011-07-01 17:37:32</generated_at>
  <created_at>2011-07-01 17:37:32</created_at>
  <updated_at>2011-07-01 17:37:32</updated_at>
</stat>

In this example we are passing in ref_id of ABC123, generated_at of 2010-02-22 and metadata with key-value pairs Food = Ice Cream and Calories = 500 (as urlencoded JSON).

curl -H "X-StatsMix-Token: API_KEY" -d "name=My%20First%20Metric∓value=20&ref_id=ABC123&generated_at=2010-02-22&meta={%22Food%22:%22Ice Cream%22,%22Calories%22:500}" api.statsmix.com/api/v2/track

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<stat>
  <id>2933452</id>
  <value>20.0</value>
  <meta>{"Food":"Ice Cream,"Calories":500}</meta>
  <profile_id>448</profile_id>
  <metric_id>124</metric_id>
  <ref_id>ABC123</ref_id>
  <generated_at>2010-02-22 00:00:00</generated_at>
  <created_at>2011-07-01 17:37:32</created_at>
  <updated_at>2011-07-01 17:37:32</updated_at>
</stat>

Metric Examples

Create a metric (POST)

curl -H "X-StatsMix-Token: API_KEY" -d "name=My%20First%20Metric" api.statsmix.com/api/v2/metrics -X POST

Update a metric (PUT)

curl -H "X-StatsMix-Token: API_KEY" -d "name=My%20Renamed%20First%20Metric" api.statsmix.com/api/v2/metrics/ID.xml -X PUT

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<metric>
  <id>950</id>
  <name>My First Metric</name>
  <profile_id>4</profile_id>
  <include_in_email>true</include_in_email>
  <sharing>none</sharing>
  <url>http://www.statsmix.com/m/bdea449e136078c07995</url>
  <created_at>2011-07-01 10:49:29 -0600</created_at>
  <updated_at>2011-07-01 10:49:29 -0600</updated_at>
</metric>

Get all metrics (index)

curl -H "X-StatsMix-Token: API_KEY" -G api.statsmix.com/api/v2/metrics

The API will return a default of up to 50 records. The parameter limit can be passed to specify the number of records to return.

The parameter profile_id can also be used to scope records to a particular profile.

The parameters start_date and end_date can be used to limit the date range based on the timestamp in a stat's generated_at.

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<metrics>
  <metric>
    <id>124</id>
    <name>New User Accounts</name>
    <profile_id>448</profile_id>
    <include_in_email>false</include_in_email>
    <sharing>none</sharing>
    <url>http://www.statsmix.com/m/3ccb81a36ae6d6fcdc31</url>
    <created_at>2011-07-01 17:21:44</created_at>
    <updated_at>2011-07-01 17:21:44</updated_at>
  </metric>
  <metric>
    <id>125</id>
    <name>Upgrades</name>
    <profile_id>448</profile_id>
    <include_in_email>true</include_in_email>
    <sharing>none</sharing>
    <url>http://www.statsmix.com/m/9e4582eb7e5cf12c18d6</url>
    <created_at>2011-06-30 19:10:15</created_at>
    <updated_at>2011-06-30 20:30:32</updated_at>
  </metric>
  <metric>
    <id>125</id>
    <name>Downgrades</name>
    <profile_id>448</profile_id>
    <include_in_email>true</include_in_email>
    <sharing>none</sharing>
    <url>http://www.statsmix.com/m/9e4582eb7e5cf12c18d6</url>
    <created_at>2011-06-30 19:10:15</created_at>
    <updated_at>2011-06-30 20:30:32</updated_at>
  </metric>
</metrics>

Stat Examples

Get all stats for a metric (index)

curl -H "X-StatsMix-Token: API_KEY" -d "metric_id=METRIC_ID&limit=LIMIT&start_date=DATETIME&end_date=DATETIME" -G api.statsmix.com/api/v2/stats

The parameter limit can be passed to specify the number of records to return (default is 50). You can also scope records to a time frame by using the parameters start_date and end_date.

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<stats>
  <stat>
    <id>2933891</id>
    <value>10.0</value>
    <profile_id>448</profile_id>
    <metric_id>124</metric_id>
    <service_id></service_id>
    <generated_at>2011-07-01 20:23:11</generated_at>
    <created_at>2011-07-01 20:23:11</created_at>
    <updated_at>2011-07-01 20:23:11</updated_at>
    <meta></meta>
  </stat>
  <stat>
    <id>2933890</id>
    <value>10.0</value>
    <profile_id>448</profile_id>
    <metric_id>124</metric_id>
    <service_id></service_id>
    <generated_at>2011-07-01 20:22:38</generated_at>
    <created_at>2011-07-01 20:22:38</created_at>
    <updated_at>2011-07-01 20:22:38</updated_at>
    <meta></meta>
  </stat>
  <stat>
    <id>2933888</id>
    <value>12.0</value>
    <profile_id>448</profile_id>
    <metric_id>124</metric_id>
    <service_id></service_id>
    <generated_at>2010-02-22 00:00:00</generated_at>
    <created_at>2011-07-01 17:37:32</created_at>
    <updated_at>2011-07-01 17:37:32</updated_at>
    <meta></meta>
  </stat>
</stats>

Create a stat (POST)

curl -H "X-StatsMix-Token: API_KEY" -d "value=VALUE&metric_id=METRIC_ID&generated_at=2010-02-22" api.statsmix.com/api/v2/stats -X POST

Create a stat with a reference id (REF_ID).

This examples uses a date. This is useful if you need to update a stat multiple times per day, but don't want to persist the stat id on your end.

curl -H "X-StatsMix-Token: API_KEY" -d "value=VALUE&metric_id=METRIC_ID&ref_id=2011-07-01" -X POST api.statsmix.com/api/v2/stats

Create a stat with metadata and custom timestamp (POST)

In this example we are passing in a generated_at of 2010-02-22 and metadata with key-value pairs Food = Ice Cream and Calories = 500 (as urlencoded JSON).

curl  -H "X-StatsMix-Token: API_KEY" -d  "metric_id=METRIC_ID&value=VALUE&generated_at=2010-02-22&meta={%22Food%22:%22Ice Cream%22,%22Calories%22:500}" -X POST api.statsmix.com/api/v2/stats

Show a stat (GET)

Notice The metric_id is required.

curl -H "X-StatsMix-Token: API_KEY" -d "metric_id=METRIC_ID" -G api.statsmix.com/api/v2/stats/STAT_ID.xml

Show a stat using ref_id (GET)

Notice The metric_id is required.

curl -H "X-StatsMix-Token: API_KEY"  -d "metric_id=METRIC_ID" -G api.statsmix.com/api/v2/stats/REF_ID.xml

Example Response:

<?xml version="1.0" encoding="UTF-8"?>
<stat>
  <id>2933888</id>
  <value>12.0</value>
  <meta></meta>
  <profile_id>448</profile_id>
  <metric_id>124</metric_id>
  <ref_id></ref_id>
  <generated_at>2010-02-22 00:00:00</generated_at>
  <created_at>2011-07-01 17:37:32</created_at>
  <updated_at>2011-07-01 17:37:32</updated_at>
</stat>

Update a stat (PUT)

Notice The metric_id is required.

curl -H "X-StatsMix-Token: API_KEY" -d "value=VALUE&metric_id=METRIC_ID" -X PUT api.statsmix.com/api/v2/stats/STAT_ID

Update a stat using ref_id (PUT)

Notice The metric_id is required.

curl -H "X-StatsMix-Token: API_KEY" -d "value=VALUE&metric_id=METRIC_ID" -X PUT api.statsmix.com/api/v2/stats/REF_ID

Delete a stat (DELETE)

Notice The metric_id is required.

curl -H "X-StatsMix-Token: API_KEY" -d "metric_id=METRIC_ID" -X DELETE api.statsmix.com/api/v2/stats/STAT_ID

Delete a stat using ref_id (DELETE)

Notice The metric_id is required.

curl -H "X-StatsMix-Token: API_KEY" -d "metric_id=METRIC_ID" -X DELETE api.statsmix.com/api/v2/stats/REF_ID