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.
The current version is 2.0. The previous version of the API (1.0) is still available, but has been deprecated.
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.
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.
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! |
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.
There are currently three resources available in the StatsMix API:
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.
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.
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.
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 is the quickest way to try the StatsMix API. Full documentation on curl can be found here.
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>
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>
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