> For the complete documentation index, see [llms.txt](https://docs.mapbox.com/api/ja/llms.txt)

# Feedback API

> **Note (beta): Public Preview for Feedback API**
> 
> Feedback API is available in Public Preview. During this phase, it may be subject to potential changes as the features and API surfaces stabilize.

> **Note (warning): Required Scope**
> 
> To use the Feedback API, access token must have the following scopes:
> 
> -   `user-feedback:read` - required to read feedback items.
> -   `user-feedback:write` - required to submit feedback items.

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](https://docs.mapbox.com/android/navigation/guides/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

**GET** : `https://api.mapbox.com/user-feedback/v1/feedback`

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](https://console.mapbox.com/feedback-explorer/) and automated data pipelines.

> **Note: Polling for updates**
> 
> 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` | A valid Mapbox [access token](https://docs.mapbox.com/api/ja/guides/#access-tokens-and-token-scopes) 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

```bash
# 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`.

```json
{
	"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",
      "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",
      "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-feedback-item-object). 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

**GET** : `https://api.mapbox.com/user-feedback/v1/feedback/{feedback_id}`

This endpoint retrieves a single feedback item by its unique ID. The response is a single [feedback item object](#feedback-api-response-object).

| Required parameters | Type | Description |
| --- | --- | --- |
| `feedback_id` | `string` | The unique identifier of the feedback item. |
| `access_token` | `string` | A valid Mapbox [access token](https://docs.mapbox.com/api/ja/guides/#access-tokens-and-token-scopes) with the `user-feedback:read` scope. |

### Example request: Get a single feedback item

```bash
# 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`.

```json
{
  "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",
  "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](#feedback-status) 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. |
| `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). |

## Create a single feedback item

**POST** : `https://api.mapbox.com/user-feedback/v1/feedback`

This endpoint creates a single feedback item with its unique ID assigned automatically. The response is a single [feedback item object](#feedback-api-response-object).

| Required parameters | Type | Description |
| --- | --- | --- |
| `access_token` | `string` | A valid Mapbox [access token](https://docs.mapbox.com/api/ja/guides/#access-tokens-and-token-scopes) with the `user-feedback:write` scope. |

Request should contain body in JSON format with the following parameters:

| Request body parameters | Type | Description |
| --- | --- | --- |
| `id` | `string` | (Optional) The unique identifier for the feedback item. If not provided, one will be generated. |
| `feedback` | `string` | The text content of the user's feedback. |
| `lat` | `number` | The latitude of the feedback's location. |
| `lon` | `number` | The longitude of the feedback's location. |
| `category` | `string` | The category assigned to the feedback. |
| `feature` | `object` | (Optional) A GeoJSON feature object (e.g., the subject of the feedback). |
| `feature.type` | `string` | The GeoJSON type, always "Feature". |
| `feature.properties` | `object` | Properties for the GeoJSON feature. |
| `feature.geometry` | `object` | The geometry object for the GeoJSON feature. |
| `feature.geometry.type` | `string` | The geometry type, (e.g., Point, LineString). |
| `feature.geometry.coordinates` | `array` | The coordinates for the geometry, as [latitude, longitude]. |
| `screenshot` | `string` | (Optional) A base64-encoded string representing a screenshot image (PNG, JPG or JPEG). |

### Example request: Post a single feedback item

```bash
# Post a single feedback item
curl -X POST "https://api.mapbox.com/user-feedback/v1/feedback?access_token=YOUR_MAPBOX_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "feedback": "The navigation tried to take me down a one-way street.",
    "lat": 37.7749,
    "lon": -122.4194,
    "category": "routing_issue",
  }'
```

---

### Example Response

Here is an example response for `POST /user-feedback/v1/feedback`.

```json
{
  "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",
  "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 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](https://www.mapbox.com/contact).