Visits

Parameter description

• user_id (Integer): User ID.
• item_id (String): Item ID.
• date_from (Date): Date, ISO format, that defines the start of the query. The maximum is 150 days.
• date_to (Date): Date, ISO format, that defines the end of the query. The maximum is 150 days.
• ending (Date, optional): Date in ISO format YYYY-MM-DD which states the time of completion of the sample. Defaults to current date and time.
• unit (String): Query unit. Possible values: day.
• last (Integer, optional): How many last days define the test.

Response Fields

• total_visits (Integer): Total visits on an item.
• visits_detail (Array): Visits detailed by country and site.
• results (Array): Visits detail grouped by time intervals. The length is defined by the unit parameter.

Total visits by user

Retrieves the total visits a user receives between date ranges.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items_visits?date_from=$DATE_FROM&date_to=$DATE_TO

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1000011398/items_visits?date_from=2021-01-01&date_to=2021-02-01

Response:

{
  "user_id": 1000011398,
  "date_from": "2021-01-01T00:00:00Z",
  "date_to": "2021-02-01T00:00:00Z",
  "total_visits": 323690,
  "visits_detail": [
    {
      "company": "mercadolibre",
      "quantity": 323690
    }
  ]
}

Total visits by article

Retrieve total visits to an article of the last two years.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/visits/items?ids=$ITEM_ID

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/visits/items?ids=MLB9992242141

Response:

{
  "MLB9992242141": 552
}

Total visits by item between date ranges

Retrieves total visits on an item between date ranges and by site.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/visits?ids=$ITEM_ID&date_from=$DATE_FROM&date_to=$DATE_TO

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/visits?ids=MCO473861358&date_from=2021-01-01&date_to=2021-02-01

Response:

{
  "item_id": "MCO473861358",
  "date_from": "2021-01-01T00:00:00Z",
  "date_to": "2021-02-01T00:00:00Z",
  "total_visits": 536,
  "visits_detail": [
    {
      "company": "mercadolibre",
      "quantity": 536
    }
  ]
}

Dated visits by user

Retrieves visits on every item of an user for a certain time window, by site. The information detail it's grouped by time intervals.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/$USER_ID/items_visits/time_window?last=$LAST&unit=$UNIT&ending=$ENDING

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/users/1000011398/items_visits/time_window?last=2&unit=day

Response:

{
  "user_id": 1000011398,
  "date_from": "2021-01-08T00:00:00Z",
  "date_to": "2021-01-10T00:00:00Z",
  "total_visits": 2923,
  "last": 2,
  "unit": "day",
  "results": [
    {
      "date": "2021-01-08T00:00:00Z",
      "total": 2205,
      "visits_detail": [
        {
          "company": "mercadolibre",
          "quantity": 2205
        }
      ]
    },
    {
      "date": "2021-01-09T00:00:00Z",
      "total": 718,
      "visits_detail": [
        {
          "company": "mercadolibre",
          "quantity": 718
        }
      ]
    }
  ]
}

Dated visits by item

Retrieves visits on an item for a certain time window, by site. The information detail it's grouped by time intervals.

Request:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/$ITEM_ID/visits/time_window?last=$LAST&unit=$UNIT&ending=$ENDING

Example:

curl -X GET -H 'Authorization: Bearer $ACCESS_TOKEN' https://api.mercadolibre.com/items/MCO471870973/visits/time_window?last=2&unit=day&ending=2025-12-29

Response:

{
  "item_id": "MCO471870973",
  "date_from": "2025-12-27T00:00:00Z",
  "date_to": "2025-12-29T00:00:00Z",
  "total_visits": 26,
  "last": 2,
  "unit": "day",
  "results": [
    {
      "date": "2025-12-27T00:00:00Z",
      "total": 16,
      "visits_detail": [
        {
          "company": "mercadolibre",
          "quantity": 16
        }
      ]
    },
    {
      "date": "2025-12-28T00:00:00Z",
      "total": 10,
      "visits_detail": [
        {
          "company": "mercadolibre",
          "quantity": 10
        }
      ]
    }
  ]
}

Errors

The following table lists the possible errors returned by the Visits API:

Status_code	Error code	Error message	Description
400	bad_request	Invalid Site ID	When the item or user does not belong to a valid local site.
400	bad_request	unknown date format	When the date_from or date_to parameter is missing or has an invalid format.
400	bad_request	invalid time window, should be smaller or equal to 150 days	When the time range exceeds the maximum allowed of 150 days.
400	bad_request	invalid date format for ending date	When the ending parameter has an invalid date format. Only YYYY-MM-DD format is accepted.
400	validation_parameters	maximum amount of items to query is 1	When trying to query more than one item at a time in the ids parameter.
400	bad_request	Invalid item ID format: $ITEM_ID	When the item ID does not follow the correct format (site prefix + numeric ID).
403	PA_UNAUTHORIZED_RESULT_FROM_POLICIES	At least one policy returned UNAUTHORIZED	When the access token is invalid, expired, or does not have the required permissions.
404	not_found	Item not found	When the item ID does not exist in the time_window endpoint.