Feedback API
To use the Feedback API, access token must have the user-feedback:read
scope.
The Mapbox Feedback API provides a unified, programmatic way to collect and access end-user feedback directly from the apps you build with Mapbox. The Feedback Agent captures user input through voice and transforms it into valuable, real-world insights. These insights help you act quickly, understand user needs faster, and improve your product effortlessly — all from right inside your app.
This API allows you to integrate feedback data directly into your own internal tools and data pipelines, giving you greater visibility into the issues and suggestions your users provide. You can track the status of feedback items as they are reviewed by Mapbox and get valuable insights about your applications.
Feedback Status
Each feedback item has a status that reflects its progress in our internal review and triage process. You can use the status
parameter to filter feedback items based on their current state.
Status | Description |
---|---|
received | We’ve successfully received your feedback and it’s awaiting review and prioritization. This is the initial status for all new feedback reports. |
fixed | The feedback has been reviewed and addressed by Mapbox. The fix will be available to end users in a few days. This is a final status and won’t change further. |
reviewed | Your feedback has been reviewed and considered internally to help guide future Mapbox product improvements. This is a final status and won’t change further. |
out_of_scope | This request is outside the scope of what Mapbox can support, or was flagged as spam or vandalism. This is a final status and won’t change further. |
Get feedback items
This endpoint returns a list of user feedback items associated with your organization's account, with options to filter, sort, and paginate the results. It's designed to power both interactive applications like the Feedback Explorer and automated data pipelines.
To periodically pull new or updated feedback into your own systems, we recommend polling this endpoint. You can track the latest updates by querying with sort_by=updated_at&order=asc
and using the after
parameter with the end_cursor
from the last response. Repeat the request until you receive an empty items
array.
Required parameters | Type | Description |
---|---|---|
access_token | string | All requests must include a Mapbox access token with the user-feedback:read scope. |
You can refine your query with the following optional parameters:
Optional parameters | Type | Description |
---|---|---|
feedback_id | array | Filter by one or more feedback item IDs. At least one must match. Example: feedback_id=06f2c4f0-862a-483e-9961-e444dfbda4cb&feedback_id=b1b1812e-4b69-49f2-bff9-8f1cd9162bd6 |
after | string | A cursor from a previous response. Use this to fetch the next page of results. |
limit | integer | The maximum number of feedback items to return. The maximum is 1000 . |
sort_by | string | The field to sort results by. Options are received_at (default), created_at , or updated_at . |
order | string | The sort direction. Options are asc (ascending, default) or desc (descending). |
status | array | Filter by one or more feedback statuses. Options: received , fixed , reviewed , out_of_scope . At least one status must match. Example: status=fixed&status=reviewed |
category | array | Filter by one or more feedback categories. Example: category=poi_details&category=other_cat |
search | string | A search phrase. Returns items where the feedback text contains the phrase. |
trace_id | array | Filter by one or more trace_id values. At least one must match. |
created_before | string | Return items created before the specified time. Use ISO 8601 format: YYYY-MM-DDTHH:mm:ss.SSSZ . |
created_after | string | Return items created after the specified time. Use ISO 8601 format. |
received_before | string | Return items received by Mapbox before the specified time. Use ISO 8601 format. |
received_after | string | Return items received by Mapbox after the specified time. Use ISO 8601 format. |
updated_before | string | Return items last updated before the specified time. Use ISO 8601 format. |
updated_after | string | Return items last updated after the specified time. Use ISO 8601 format. |
Example request: Get feedback items
# Get the first 10 feedback items with 'fixed' status in the 'poi_details' category
curl "https://api.mapbox.com/user-feedback/v1/feedback?limit=10&status=fixed&category=poi_details&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
# Get all feedback updated since the start of July 2025, sorted by update time
curl "https://api.mapbox.com/user-feedback/v1/feedback?status=received&status=fixed&status=reviewed&status=out_of_scope&updated_after=2025-07-01T00:00:00Z&sort_by=updated_at&order=asc&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
# Get the next page of results after a specific cursor
curl "https://api.mapbox.com/user-feedback/v1/feedback?after=eyJpZCI6IjAxOTg1YWQ2LWE4ZjEtNzdkZS1iODkxLWU4NTVhNGI3ZTQ5NiIsInRpbWVzdGFtcCI6IjIwMjUtMDctMzBUMTA6MTc6NTQuMTYxWiJ9&access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Example Response
Here is an example response for a query to GET /user-feedback/v1/feedback?limit=2
.
{
"has_before": false,
"start_cursor": "eyJpZCI6IjAxOTg1YWQ2LWE4ZjEtNzdkZS1iODkxLWU4NTVhNGI3ZTQ5NiIsInRpbWVzdGFtcCI6IjIwMjUtMDctMzBUMTA6MTc6NTQuMTYxWiJ9",
"end_cursor": "eyJpZCI6IjAxOTg1YWQyLTE3MzUtNzNmYS1iMjE2LTI3NDk1YmJjYzFkYiIsInRpbWVzdGFtcCI6IjIwMjUtMDctMzBUMTA6MTI6NTQuNzA5WiJ9",
"has_after": true,
"items": [
{
"id": "40eae4c7-b157-4b49-a091-7e1099bba77e",
"status": "fixed",
"category": "poi_details",
"feedback": "I want to add a note that to get into this apartment building you have to put in a code for 396.",
"location": {
"place_name": "Financial District, Boston, Massachusetts, United States",
"lon": -71.05011393295,
"lat": 42.351484923828
},
"trace_id": "a35ab5db-dd99-45a6-966b-fc6bda2181b9",
"metadata": {
"userId": "user-123",
"appVersion": "2.5.1"
},
"received_at": "2025-07-28T14:10:30.123Z",
"created_at": "2025-07-28T14:10:25.000Z",
"updated_at": "2025-07-28T14:10:30.123Z"
},
{
"id": "8b1eec47-a3f2-4a6d-a2d9-5e8c1f4a9b0c",
"status": "received",
"category": "routing_issue",
"feedback": "The navigation tried to take me down a one-way street.",
"location": {
"place_name": "123 Main St, Anytown, USA",
"lon": -122.4194,
"lat": 37.7749
},
"trace_id": "9c12345e-45a6-45a6-966b-abcdef123456",
"metadata": {
"name": "com.mapbox.dash.app",
"userId": "54f338c6-7176-4256-83b9-a7f34fb3651b",
"version": "0.46.0.1122714.67f83f3.2025.07.25.Handheld.devRelease",
"sessionId": null
},
"received_at": "2025-07-27T11:22:05.456Z",
"created_at": "2025-07-27T11:21:59.000Z",
"updated_at": "2025-07-29T09:00:00.000Z"
}
]
}
Feedback API response object
The response to a GET /user-feedback/v1/feedback
request is an object containing a list of feedback items and cursors for pagination.
Property | Type | Description |
---|---|---|
items | array | An array of feedback item objects. The array will be empty if no results match the query. |
has_before | boolean | Indicates if there are more items before the current page. If true , you can use the start_cursor to fetch the previous page. |
start_cursor | string | A cursor pointing to the first item in the returned set. Pass this value to the before parameter in the next request to get the previous page. |
has_after | boolean | Indicates if there are more items after the current page. If true , you can use the end_cursor to fetch the next page. |
end_cursor | string | A cursor pointing to the last item in the returned set. Pass this value to the after parameter in the next request to get the next page. |
Get a single feedback item
This endpoint retrieves a single feedback item by its unique ID. The response is a single feedback item object.
Required parameters | Type | Description |
---|---|---|
feedback_id | string | The unique identifier of the feedback item. |
access_token | string | All requests must include a Mapbox access token with the user-feedback:read scope. |
Example request: Get a single feedback item
# Get a specific feedback item by its ID
curl "https://api.mapbox.com/user-feedback/v1/feedback/40eae4c7-b157-4b49-a091-7e1099bba77e?access_token=YOUR_MAPBOX_ACCESS_TOKEN"
Example Response
Here is an example response for GET /user-feedback/v1/feedback/8b1eec47-a3f2-4a6d-a2d9-5e8c1f4a9b0c
.
{
"id": "8b1eec47-a3f2-4a6d-a2d9-5e8c1f4a9b0c",
"status": "received",
"category": "routing_issue",
"feedback": "The navigation tried to take me down a one-way street.",
"location": {
"place_name": "123 Main St, Anytown, USA",
"lon": -122.4194,
"lat": 37.7749
},
"trace_id": "9c12345e-45a6-45a6-966b-abcdef123456",
"metadata": {
"name": "com.mapbox.dash.app",
"userId": "54f338c6-7176-4256-83b9-a7f34fb3651b",
"version": "0.46.0.1122714.67f83f3.2025.07.25.Handheld.devRelease",
"sessionId": null
},
"received_at": "2025-07-27T11:22:05.456Z",
"created_at": "2025-07-27T11:21:59.000Z",
"updated_at": "2025-07-29T09:00:00.000Z"
}
The feedback item object
Each object in the items
array is a single piece of feedback and contains the following properties:
Property | Type | Description |
---|---|---|
id | string | The unique identifier for the feedback item. |
status | string | The status of the item. See the Feedback Status section for possible values. |
category | string | The category assigned to the feedback. |
feedback | string | The text content of the user's feedback. |
location | object | An object containing geographic information for the feedback. |
location.place_name | string | A human-readable string describing the location (e.g., an address or place name). |
location.lon | number | The longitude of the feedback's location. |
location.lat | number | The latitude of the feedback's location. |
trace_id | string | An optional ID provided by the client, used to correlate the feedback with an event in your system. |
metadata | object | Custom data associated with the feedback item. |
received_at | string | The timestamp (in ISO 8601 format) when the feedback was received by Mapbox. |
created_at | string | The timestamp (in ISO 8601 format) when the feedback was created by the end-user. |
updated_at | string | The timestamp (in ISO 8601 format) of the last update to the feedback item (e.g., a resolution change). |
Feedback API pricing
Feedback API is free during the Public Preview as part of Feedback Agent, which also includes access to Feedback Explorer.
At General Availability, customers using Feedback Agent will incur a charge of $0.02 per feedback item, with data retained only for a limited period. This charge includes access to Feedback Explorer and the Feedback API.
For custom categories, contractual SLAs on map and navigation feedback resolution, or advanced reporting, contact us.