Important Note:
This article has been moved to our Developer Center, and will no longer be updated on this site. Here is the newest version of our Taxonomy API.
The Taxonomy API grants Scholarship, Growth, and Enterprise clients the ability to programmatically maintain their event schema in the Taxonomy tab.
Note that some functions are available for all customers on the Scholarship, Growth, and Enterprise plan, while others like edits to the schema, are only available to customers who have purchased the Taxonomy add-on.
IMPORTANT NOTE: Please read the Request Limits section thoroughly. Exceeding any of these limits will return a 429 error.
Table of Contents
API Endpoints
Authenticate via basic authentication with the credentials API_Key:Secret_Key
. Below are the supported endpoints.
Important Note:
- You may have to URL encode special characters in the names of event types, event properties, and user properties. For example, 'Play Song' would be 'Play%20Song'. Here is an encoding reference. In addition, note that the examples in this article contain backslash syntax in order to escape characters when using curl. If you are not using curl, then you should not encode your request with backslash escape characters.
Methods | Endpoints |
---|---|
GET Event Category |
https://amplitude.com/api/2/taxonomy/category/<category_name> |
PUT|DELETE Event Category |
https://amplitude.com/api/2/taxonomy/category/<category_id> |
GET|POST Event Category |
https://amplitude.com/api/2/taxonomy/category |
GET|PUT|DELETE Event Type |
https://amplitude.com/api/2/taxonomy/event/<event_type> |
GET|POST Event Type |
https://amplitude.com/api/2/taxonomy/event |
GET|PUT|DELETE Event Property |
https://amplitude.com/api/2/taxonomy/event-property/<event_property> |
GET|POST Event Property |
https://amplitude.com/api/2/taxonomy/event-property |
GET|PUT|DELETE User Property |
https://amplitude.com/api/2/taxonomy/user-property/<user_property> |
GET|POST User Property |
https://amplitude.com/api/2/taxonomy/user-property |
Request Limits
For each endpoint, there is a concurrent and a rate limit. The concurrent limit restricts the amount of requests you can run at the same time, while the rate limit restricts the total number of queries you can run per hour. The limits are per project (i.e. per API Key), and exceeding any of these limits will return a 429 error.
The endpoints take into account a concept of cost per query. Below are the max costs per API Key:
- Concurrent Cost Limit: You can run queries that collectively add up to 4 cost at the same time.
- Period Cost Limit: You can run up to 7200 cost per hour.
Cost structure of each endpoint:
- GET: 1 cost
- PUT: 2 cost
- POST: 2 cost
- DELETE: 2 cost
HTTP Status Codes and Failed Requests
Error Code | Description |
---|---|
200 |
Request successful. |
400 |
Request is malformed. |
404 |
Not found. |
429 |
Too many requests for a secret key. |
513 |
Server error. A request with this response can be retried without any risk of duplicating an event. |
Event Category
The following calls will allow you to Create, Get, Update, and Delete event categories.
Create an Event Category
Parameters | Description |
---|---|
category_name (required) string |
Name of the category. This is the only required parameter for the call. |
Below is an example request:
curl -u API_Key:Secret_Key -X POST 'https://amplitude.com/api/2/taxonomy/category' --data-urlencode 'category_name=category_test'
Below is an example response:
{ "success" : true } Or { "success" : false, "errors" : [ { "message" : "error info" } ]
Get an Event Category
Parameters | Description |
---|---|
category_name (required) string |
Name of the category. This is the only required parameter for the call. |
Below is an example request.
curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/category/category_name'
Below is an example response:
{ "data" : { "name" : "category_test", "id" : 4786 }, "success" : true } Or { "success" : false, "errors" : [ { "message" : "Not found" } ] }
Get all Event Categories
There are no required parameters for this call. Below is an example request.
curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/category'
Below is an example response:
{ "success" : true, "data" : [ { "name" : "category_test", "id" : 4786 } ] } Or { "success" : false, "errors" : [ { "message" : "Not found" } ] }
Update an Event Category
Parameters | Description |
---|---|
category_id (required) integer |
ID of an existing category. ID can be found with a GET call above. |
category_name (required) string |
New name of the category. |
Below is an example request.
curl -u API_Key:Secret_Key -X PUT 'https://amplitude.com/api/2/taxonomy/category/4786' --data-urlencode 'category_name=category_testNew'
Below is an example response:
{ { "success" : true } Or { "errors" : [ { "message" : “Not found” } ], "success" : false } }
Delete an Event Category
Parameters | Description |
---|---|
category_id (required) integer |
ID of an existing category. ID can be found with a GET call above. |
Below is an example request.
curl -u API_Key:Secret_Key -X DELETE 'https://amplitude.com/api/2/taxonomy/category/4786'
Below is an example response:
{ "success" : true } Or { "success" : false, "errors" : [ { "message" : "Not found" } ] }
Event Type
The following calls will allow you to Create, Get, Update, and Delete event types.
Create an Event Type
Parameters | Description |
---|---|
event_type (required) string |
Name of the event type. |
category (optional) string |
Name of the event type's category. |
description (optional) string |
Additional details you would like to add to the event type. |
Below is an example request.
curl -u API_Key:Secret_Key -X POST 'https://amplitude.com/api/2/taxonomy/event' --data-urlencode 'event_type=add_event' --data-urlencode 'category=category_test' --data-urlencode 'description=add events'
Below is an example response:
{ "success" : true } Or { "errors" : [ { "message" : “some errors info” } ], "success" : false }
Get an Event Type
Parameters | Description |
---|---|
event_type (required) string |
Name of the event type. |
Below is an example request.
curl -u API_Key:Secret_Key -X GET ''https://amplitude.com/api/2/taxonomy/event/add_event'
Below is an example response:
{ "success" : true, "data" : { "category" : { "name" : "category_test" }, "description" : "add events", "event_type" : "add_event" } } Or { "success" : false, "errors" : [ { "message" : "Not found" } ] }
Get all Event Types
There are no required parameters for this call. Below is an example request.
curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/event'
Below is an example response:
{ "success": true, "data": [{ "category": { "name": "category_test" }, "description": "add events", "event_type": "add_event" }, { "category": null, "event_type": "Visit tab: timelines.detail", "description": null }, { "description": null, "category": null, "event_type": "Visit tab: timelines.realtime" } ] } Or { "success" : false, "errors" : [ { "message" : "Not found" } ] }
Update an Event Type
Parameters | Description |
---|---|
event_type (required) string |
Current name of an existing event type |
new_event_type (optional) string |
New name of an event_type. |
category (optional) string |
Current category name of the event type. |
description (optional) string |
Additional details you would like to add to the event type. |
Below is an example request.
curl -u API_Key:Secret_Key -X PUT 'https://amplitude.com/api/2/taxonomy/event/add_event' --data-urlencode 'category=category_test' --data-urlencode 'description=new add events' --data-urlencode ‘new_event_type=new_add_events'
Below is an example response:
{ "success" : true } Or { "errors" : [ { "message" : “some errors info” } ], "success" : false }
Delete an Event Type
Parameters | Description |
---|---|
event_type (required) string |
Name of the planned event type that needs to be deleted. |
Below is an example request.
curl -u API_Key:Secret_Key -X DELETE 'https://amplitude.com/api/2/taxonomy/event/add_event'
Below is an example response:
{ "success" : true } Or { "success" : false, "errors" : [ { "message" : "Attempted to remove an event, \"add_event'\", that is not a planned event." } ] }
Event Property
The following calls will allow you to Create, Get, Update, and Delete event property types.
Create an Event Property
Parameters | Description |
---|---|
event_type (required) string |
Name of the event associated with the event property. |
event_property (required) string |
Name you would like to give your event property. |
description (optional) string |
Additional details you would like to add to the event property. |
type (optional) string |
Data type of the event property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any'. |
regex (optional) string |
Regular expression, custom regex that can be used for pattern matching or more complex values. (e.g. property zip code must have pattern [0-9]{5} ) |
enum_values (optional) list |
List of allowed values. |
is_array_type (optional) boolean |
True or false values only. |
is_required (optional) boolean |
True or false values only. If set to `true`, event types missing this property will be flagged on their Taxonomy page. |
Below is an example request.
curl -u API_Key:Secret_Key -X POST 'https://amplitude.com/api/2/taxonomy/event-property' --data-urlencode 'event_type=add_event' --data-urlencode 'event_property=user' --data-urlencode 'description= user id' --data-urlencode 'type=string' --data-urlencode 'regex=[0-9]{5}' --data-urlencode 'is_array_type=false' --data-urlencode 'is_required=false'
Below is an example response:
{ "success" : true } Or { "errors" : [ { "message" : “some errors info” } ], "success" : false }
Get an Event Property
Parameters | Description |
---|---|
event_type (required) string |
Name of the event type to which the event property belongs to. |
event_property string |
Name you would like to give your event property. |
Below is an example request.
curl -u API_Key:Secret_Key -X GET ''https://amplitude.com/api/2/taxonomy/event-property/user?event_type=add_event'
Below is an example response:
{ "data" : { "description" : "user id", "event_type" : "add_event", "event_property" : "user", "regex": null, "is_required": true, "is_array_type": true, "enum_values": null, "type": "string" }, "success" : true } Or { "success" : false, "errors" : [ { "message" : "Not found" } ] }
Get all Event Properties
This call allows you to retrieve all event property types associated with a specified event type.
Parameters | Description |
---|---|
event_type (required) string |
Name of the event type to which the event properties belong to. |
Below is an example request.
curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/event-property?event_type=add event'
Below is an example response:
{ "data" : [ { "description" : "user id", "event_type" : "add_event", "event_property" : "user", "regex": null, "is_required": true, "is_array_type": true, "enum_values": null, "type": "string" "event_property" : "user", "event_type" : "add_event", "description" : "user id" } ], "success" : true } Or { "success" : false, "errors" : [ { "message" : "Not found" } ] }
Update an Event Property
Parameters | Description |
---|---|
event_type (required) string |
Name of the associated event type. |
event_property (required) string |
Existing name of the event property that needs to be updated. |
new_event_property (optional) string |
New name of the event property. |
description (optional) string |
Additional details you would like to add to the event property type. |
type (optional) string |
Data type of the event property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any'. |
regex (optional) string |
Regular expression or custom regex that can be used for pattern matching and more complex values (e.g. 'zip code' property must have pattern [0-9]{5} ). |
enum_values (optional) string |
List of allowed values, separated by comma (eg: red, yellow, blue). |
is_array_type (optional) string |
Specifies whether or not property value is an array. Allowable values are 'true' and 'false'. |
is_required (optional) string |
Allowable values are 'true' and 'false'. If set to `true`, event types missing this property will be flagged on their Taxonomy page. |
Below is an example request.
curl -u API_Key:Secret_Key -X PUT 'https://amplitude.com/api/2/taxonomy/event-property/user' --data-urlencode 'description=user name' --data-urlencode 'event_type=add_event_new' --data-urlencode 'type=string' --data-urlencode 'regex=[0-9]{5}' --data-urlencode 'is_array_type=false' --data-urlencode 'is_required=true-data-urlencode 'new_event_property_value=user_name'
Below is an example response:
{ "success" : true } Or { "errors" : [ { "message" : “some errors info” } ], "success" : false }
Delete an Event Property
Parameters | Description |
---|---|
event_type (required) string |
The event type which the event property belongs to. |
event_property (required) string |
The name of the event property that needs to be deleted. |
Below is an example request.
curl -u API_Key:Secret_Key -X DELETE 'https://amplitude.com/api/2/taxonomy/event-property/user?event_type=/add_event'
Below is an example response:
{ "success" : true } Or { "success" : false, "errors" : [ { "message" : "Not found" } ] }
User Property
The following calls will allow you to Create, Get, Update, and Delete user property types.
Create a User Property
Parameters | Description |
---|---|
user_property (required) string |
Name of the user property. |
description (optional) string |
Additional details you would like to add to the user property. |
type (optional) string |
Data type of the user property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any' |
regex (optional) string |
Regular expression or custom regex that can be used for pattern matching and more complex values (e.g. 'zip code' property must have pattern [0-9]{5} ). |
enum_values (optional) string |
List of allowed values, separated by comma (eg: red, yellow, blue). |
is_array_type (optional) string |
Specifies whether or not property value is an array. Allowable values are 'true' and 'false'. |
Below is an example request.
curl -u API_Key:Secret_Key -X PUT 'https://amplitude.com/api/2/taxonomy/user-property' --data-urlencode 'user_property=age' --data-urlencode 'description=I do not know' --data-urlencode 'type=string' --data-urlencode 'regex=[0-9]{1,2}' --data-urlencode 'is_array_type=false'
Below is an example response:
{ "success" : true } Or { "success" : false }
Get a User Property
Parameters | Description |
---|---|
user_property (required) string |
Name of the user property. The only required parameter of this request. |
Below is an example request.
curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/user-property/age'
Below is an example response:
{ "data" : { "user_property" : "age ", "description" : "how old this user is", "regex": null, "is_array_type": false, "enum_values": null, "type": "string" }, "success" : true } Or { "success" : false, "errors" : [ { "message" : "Not found" } ] }
Get all User Properties
There are no required parameters for this call. Below is an example request.
curl -u API_Key:Secret_Key -X GET 'https://amplitude.com/api/2/taxonomy/user-property'
Below is an example response:
{ "success" : true, "data" : [ { "user_property" : "age ", "description" : "how old this user is", "regex": null, "is_array_type": false, "enum_values": null, "type": "string" ] } Or { "success" : false, "errors" : [ { "message" : "Not found" } ] }
Update a User Property
Parameters | Description |
---|---|
user_property (required) string |
Name of the existing user property type. |
new_user_property (optional) string |
New name of the user property type. |
description (optional) string |
Additional details you would like to add to the user property type. |
type (optional) string |
Data type of the user property. Acceptable values are 'string', 'number', 'boolean', 'enum', and 'any' |
regex (optional) string |
Regular expression or custom regex that can be used for pattern matching and more complex values (e.g. 'zip code' property must have pattern [0-9]{5} ). |
enum_values (optional) string |
List of allowed values, separated by comma (eg: red, yellow, blue). |
is_array_type (optional) string |
Specifies whether or not property value is an array. Allowable values are 'true' and 'false'. |
Below is an example request.
curl -u API_Key:Secret_Key -X PUT 'https://amplitude.com/api/2/taxonomy/user-property/age' --data-urlencode 'description=first name' --data-urlencode 'new_user_property_value=first_name' --data-urlencode 'type=string' --data-urlencode 'regex=None' --data-urlencode 'enum_values=None' --data-urlencode 'is_array_type=false'
Below is an example response:
{ "success" : true } Or { "errors" : [ { "message" : “Not found” } ], "success" : false }
Delete a User Property
Parameters | Description |
---|---|
user_property (required) string |
Name of the user property type that needs to be deleted. |
Below is an example request.
curl -u API_Key:Secret_Key -X DELETE 'https://amplitude.com/api/2/taxonomy/user-property/age'
Below is an example response:
{ "success" : true } Or { "success" : false, "errors" : [ { "message" : "Not found" } ] }