Overview
Welcome to the documentation and examples for using the ThoughtMetric API!
With the ThoughtMetric API, you can easily integrate our powerful analytics and attribution features into your own applications and workflows.
Authentication
All REST API queries require a valid ThoughtMetric access token.
To get your access token your account must first be granted access to interact with the API. Please reach out to your customer support rep to be granted API access.
Once your account is granted access, you will be able to find your access token under the “API” section of your account settings page.
To authenticate with the ThoughtMetric API, you need to send your API key as a bearer token in the Authorization header of each request.
curl -X GET <https://thoughtmetric.com/api/v1/performance_data> \\ -H "Authorization: Bearer YOUR_API_KEY"
Rate Limits
To ensure fair use and stability of the ThoughtMetric API, there is a rate limit of 15 requests per minute.
Limit: 15 requests per minute
Scope: The limit applies per API key.
Response: If you exceed the rate limit, you will receive a
429 Too Many Requestsresponse status.
Endpoints
The base URL for all API requests is:
https://thoughtmetric.io/api/v1/
Performance Data
GET /api/v1/performance_data
The performance data endpoint is used to query store performance metrics such as total sales, orders, and spend.
Parameters
projectId: The id of the project (store) that you want data from. It can be found in the url when on the ThoughtMetric main dashboard for the store.startDate: Start date of the date range you want to query. The format is 2024-01-01.endDate: End date of the date range you want to query. The format is 2024-01-01.interval: The granularity that you want the data grouped in. Options are day, week, month, year.
Example
Request:
curl -X GET '<https://thoughtmetric.io/api/v1/performance_data?projectId=3349&startDate=2024-01-01&endDate=2024-05-05&interval=day>' \\ -H "Authorization: Bearer YOUR_API_KEY"
Response:
{ "total": { "visits": 2524.0, "total_duration": 89105.0, "total_pageviews": 4907.0, "orders": 52.0, "view_contents": 0.0, "add_to_carts": 0.0, "leads": 0.0, "gross_sales": 28840.59, "total_discounts": 2262.47, "total_refund": 0.0, "net_sales": 26578.12, "total_shipping": 25.68, "total_tax": 5034.64, "total_sales": 31638.44, "item_quantity": 87.0, "spend": 0.0, "converted_spend": 0.0, "aov": 608.43, "conversion_rate": 2.06, "cac_blended": 0.0, "mer": 0.0 }, "total_last_period": { "visits": 0.0, "total_duration": 0.0, "total_pageviews": 0.0, "orders": 0.0, "view_contents": 0.0, "add_to_carts": 0.0, "leads": 0.0, "gross_sales": 0.0, "total_discounts": 0.0, "total_refund": 0.0, "net_sales": 0.0, "total_shipping": 0.0, "total_tax": 0.0, "total_sales": 0.0, "item_quantity": 0.0, "spend": 0.0, "converted_spend": 0.0, "aov": 0.0, "conversion_rate": 0.0, "cac_blended": 0.0, "mer": 0.0 }, "over_time": [ { "time": "2024-07-13T00:00:00.000+00:00", "visits": 0.0, "total_duration": 0.0, "total_pageviews": 0.0, "orders": 0.0, "view_contents": 0.0, "add_to_carts": 0.0, "leads": 0.0, "gross_sales": 0.0, "total_discounts": 0.0, "total_refund": 0.0, "net_sales": 0.0, "total_shipping": 0.0, "total_tax": 0.0, "total_sales": 0.0, "item_quantity": 0.0, "spend": 0.0, "converted_spend": 0.0, "aov": 0.0, "conversion_rate": 0.0, "cac_blended": 0.0, "mer": 0.0 }, ... ] }
Performance Data By Channel
GET /api/v1/performance_data_by_channel
The performance data by channel endpoint is used to query store performance metrics broken down by channel.
Parameters
projectId: The id of the project (store) that you want data from. It can be found in the url when on the ThoughtMetric main dashboard for the store.startDate: Start date of the date range you want to query. The format is 2024-01-01.endDate: End date of the date range you want to query. The format is 2024-01-01.interval: The granularity that you want the data grouped in. Options are day, week, month, year.
Example
Request:
curl -X GET '<https://thoughtmetric.io/api/v1/performance_data_by_channel?projectId=3349&startDate=2024-01-01&endDate=2024-05-05&interval=day>' -H "Authorization: Bearer YOUR_API_KEY"
Customer LTV
GET /api/v1/customer_ltv
This endpoint is used to query customer ltv metrics.
Parameters
projectId: The id of the project (store) that you want data from. It can be found in the url when on the ThoughtMetric main dashboard for the store.startDate: Start date of the date range you want to query. The format is 2024-01-01.endDate: End date of the date range you want to query. The format is 2024-01-01.interval: The granularity that you want the data grouped in. Options are day, week, month, year.
Example
Request:
curl -X GET '<https://thoughtmetric.io/api/v1/customer_ltv?projectId=3349&startDate=2024-01-01&endDate=2024-05-05&interval=day>' -H "Authorization: Bearer YOUR_API_KEY"
Customer LTV By Channel
GET /api/v1/customer_ltv_by_channel
This endpoint is used to query customer ltv metrics broken down by channel
Parameters
projectId: The id of the project (store) that you want data from. It can be found in the url when on the ThoughtMetric main dashboard for the store.startDate: Start date of the date range you want to query. The format is 2024-01-01.endDate: End date of the date range you want to query. The format is 2024-01-01.interval: The granularity that you want the data grouped in. Options are day, week, month, year.
Example
Request:
curl -X GET '<https://thoughtmetric.io/api/v1/customer_ltv_by_channel?projectId=3349&startDate=2024-01-01&endDate=2024-05-05&interval=day>' -H "Authorization: Bearer YOUR_API_KEY"
New & Returning Customer Data
GET /api/v1/new_returning_customer_data
This endpoint is used to query new vs returning customer metrics.
Parameters
projectId: The id of the project (store) that you want data from. It can be found in the url when on the ThoughtMetric main dashboard for the store.startDate: Start date of the date range you want to query. The format is 2024-01-01.endDate: End date of the date range you want to query. The format is 2024-01-01.interval: The granularity that you want the data grouped in. Options are day, week, month, year.
Example
Request:
curl -X GET '<https://thoughtmetric.io/api/v1/new_returning_customer_data?projectId=3349&startDate=2024-01-01&endDate=2024-05-05&interval=day>' -H "Authorization: Bearer YOUR_API_KEY"
New & Returning Customer Data By Channel
GET /api/v1/new_returning_customer_data_by_channel
This endpoint is used to query new vs returning customer metrics broken down by channel.
Parameters
projectId: The id of the project (store) that you want data from. It can be found in the url when on the ThoughtMetric main dashboard for the store.startDate: Start date of the date range you want to query. The format is 2024-01-01.endDate: End date of the date range you want to query. The format is 2024-01-01.interval: The granularity that you want the data grouped in. Options are day, week, month, year.
Example
Request:
curl -X GET '<https://thoughtmetric.io/api/v1/new_returning_customer_data_by_channel?projectId=3349&startDate=2024-01-01&endDate=2024-05-05&interval=day>' -H "Authorization: Bearer YOUR_API_KEY"
All Orders
GET /api/v1/all_orders
The performance data endpoint is used to query new vs returning customer metrics broken down by channel.
Parameters
projectId: The id of the project (store) that you want data from. It can be found in the url when on the ThoughtMetric main dashboard for the store.startDate: Start date of the date range you want to query. The format is 2024-01-01.endDate: End date of the date range you want to query. The format is 2024-01-01.interval: The granularity that you want the data grouped in. Options are day, week, month, year.
Example
Request:
curl -X GET '<https://thoughtmetric.io/api/v1/all_orders?projectId=3349&startDate=2025-01-01&endDate=2025-05-05&interval=day>' -H "Authorization: Bearer YOUR_API_KEY"