Troubleshooting

Analyze statistics and invoices

This guide covers how your account statistics correspond to your invoices. If you'd like to read more about either of these products in depth, jump to the Statistics FAQs or the Invoices FAQs.

If you still have questions after reading this guide, contact support. We’re happy to help!

How Mapbox statistics relate to invoices

Mapbox offers several APIs for customers use; each API serves a different purpose depending on each use case. For a full list of all the APIs that are available right now, visit our developer’s page. Visit our API documentation for examples of different techniques for accessing Mapbox web services APIs.

We meter each of our APIs individually—meaning we price each API separately from the others. Check out our list of what API requests we include with each plan to see a current list of what your plan offers.

Mapbox statistics

Your Statistics page displays analytics information about API services used by your Mapbox account. To access the Statistics page, log into your account and navigate to www.mapbox.com/account/statistics. From this page, you can see your complete account statistics or view the API statistics for each of your access tokens:

Filtering statistics by access token

Results can adjusted by specific time frames (week, month, year, or a custom date range).

For each of the Mapbox APIs you’ve used within the specified period, you can see information on the referring URLs (websites using your maps), map IDs, countries, and browsers from which the requests originated.

Note: You will only see the statistics for the APIs you’ve used within the period you specified.

Map view statistics

Statistics: key terms

  • Access tokens. The unique keys that associate Mapbox web services with your account. Tokens can be managed from the account dashboard UI or the command line.
  • Map view. The unit of metering services from our Maps APIs.
  • Monthly active user (MAU). The unit of metering services for the native Mobile SDKs. Note that not all hybrid mobile application frameworks are metered on MAUs. MAUs are not broken down by access token.
  • Static maps. The number of requests made to the Static API on the selected access token.
  • Ephemeral geocodes. The number of requests made to the Geocoding API (mapbox.places endpoint) on the selected access token.
  • Permanent geocodes. The number of requests made to the Geocoding API (mapbox.places-permanent endpoint) on the selected access token.
  • Directions. The number of requests made to the Directions API on the selected access token.
  • Optimization. The number of requests made to the Optimization API on the selected access token.
  • Elements. The unit of metering services for the Matrix API.
  • Connected apps. Defined applications that are authorized to access your maps and data.

Statistics: FAQs

What services are included with my plan?

Refer to the Account FAQ: API requests included in each plan.

What timezone are my statistics in?

Statistics are in UTC (aka Greenwich Mean Time).

How long does it take for my statistics to be displayed?

The Statistics page populates your usage data within 2-3 hours, but may take up to 6 hours.

Are static map views a subset of total map views?

Yes. Maps served by the Static API are non-interactive PNG images that are metered as one map view to one request. Static maps are displayed as a subset of total map views on the Statistic page, and are not billed twice.

What are Other or Not set referring URLs?

Other or Not set referring URLs are referrers from GL JS maps that our statistics engine is having trouble processing. Upgrading to GL JS v0.51.0 or later will reduce instances of referrers that cannot be parsed. Support for Internet Explorer is not yet included.

Why does the sum of my API usage for each token not equal the API usage when I filter by All tokens?

When you filter your statistics by All tokens, we show you all your billable statistics. When you filter your statistics by an individual token, we show you the relative API usage that token has authenticated.

There are two reasons your statistics for all tokens adds up to more than each individual token.

  1. You have a mobile application that’s billed on Monthly Active Users instead of map views. The statistics page does not display MAU count by token. On a per-token basis, the statistics page will switch to show the number of map views generated by all your end users (these map views are not billed).

  2. You have usage from a deleted access token. If an access token is deleted during your billing cycle, filtering your statistics by All tokens will show traffic that was authenticated with the deleted token (even though that token doesn’t show up in the drop-down filter list).

This is particularly helpful if you build different apps with different Mapbox access tokens. You can filter your statistics by each token to see how your end users are interacting with your maps for each application. If you want to see any statistics that relate to your invoices, filter your statistics by All tokens.

We’re working on showing data for deleted access tokens. If you require information about deleted access tokens, let us know. We’d love to hear from you!

I expect to see only Monthly Active User (MAU) statistics, but I’m seeing map views. What’s happening?

Monthly Active Users (MAUs) are the unit of measurement for the native Mapbox Maps SDKs for iOS, Android, and React Native, as well as mobile applications built with the Maps SDK for Unity. Not all hybrid frameworks are metered on MAUs. If you have questions about how your mobile application is being metered, contact support by selecting your mobile product on our contact form and include a description of your issue.

Can I view my MAUs by token?

The Statistics page does not display mobile apps by specific token. Instead, when you filter by access token to see specific MAUs for mobile application, the view changes to map views. This is helpful to see which of your mobile applications are seeing the most map interactions, but not so helpful if you want to see which access token each of your mobile apps are using.

Feel free to contact support with questions about this functionality.

Can I export a CSV file of my Statistics data?

We don't yet support an export feature on the Statistics page but would love to hear your feature requests around a CSV download option - contact us to share your use case.

Mapbox invoices

The Invoices page displays your complete billing history for your Mapbox account. Every month, a new invoice is generated. Invoices are generated even if you have not incurred charges for that billing period. You may have multiple pages of invoices if you've been a customer for more than a year. Click on the individual invoices to open them.

Example invoice

Each invoice has three parts: 1) billing period, 2) overages for services that exceed what's included with your plan, 3) line item amounts for each of the services.

Example invoice

Invoices: Key terms

  • Pay-as-you-go. Monthly subscription with $0 upfront cost and a set amount of API requests included each billing period.
  • Commercial. Monthly subscription that licenses Commercial applications. This plan is $499 upfront and an includes an alottment of API requests each billing period.
  • Overages. Requests that exceed the free monthly allotment of PAYG & Commercial are considered overages, and will be automatically billed to the credit card on file.
  • Billing period. Your monthly billing cycle begins on the day you create your Mapbox account. Invoices will be automatically posted to your Invoices page and charged to the registered credit card on their due dates.
  • Prepayment credit. It's possible to add prepaid credit to your account from your billing settings. Utilizing the prepaid option allows you to add a certain dollar amount of credit to your account and then remove the credit card to control your spending in a given period.

Invoices: FAQs

Can I add custom information to my invoices?

Yes! See our Account FAQ for instructions.

Can I set a spending threshold that caps my account's usage?

We do not yet support a spending cap. For now, the best way to create predictable monthly spending is by adding a set amount of prepaid credit and by monitoring your account statistics and your invoices closely. Once your invoice reaches an amount you'd like to pay for that billing period, you can rotate your access tokens (making your older tokens invalid).

When you rotate your access tokens, your production maps will become disabled and your account will have no more traffic. When you're ready to activate your account again, you can rotate your new tokens into your implementation and your maps will be re-activated.

Can I set notifications based on my account usage?

You'll receive an email with the subject "[Mapbox Billing] 100% of plan's usage exceeded" when your account exceeds the free allotment of services, but we don't yet offer configurable email or SMS notifications. Let us know if this is a feature you'd like to see!

Can I download my past invoices?

Log in to your account, navigate to www.mapbox.com/account/invoices, open each invoice individually and use the print button to Save to PDF.

Can I add a secondary billing email address for my accounting department?

As we scope out adding this feature to the account dashboard, we recommend setting up a forwarding rule in your email client that automatically forwards emails tiled "Mapbox payment receipt" to the relevant stakeholders. Let us know if this feature is important to you!

Can I see my coupon reflected on my invoice?

You can view your coupon reflected as a discount on any of your invoices:

Example invoice with discount

To view the coupon code on your account settings, navigate to your account billing settings.

My Statistics page and my Invoices page differ. What's happening?

If you've set the custom date on your Statistics page to match your billing cycle and notice a discrepancy in the values of services you were billed for, it's most likely an issue with timezones. Requests attributed to your billing period that were not invoiced during that month will roll over to the next invoice. Contact support with questions about specific invoices.

What payment methods are available?

You can pay for your Mapbox account with the following credit, debit, prepaid, and gift cards: Visa, MasterCard, American Express, JCB, Discover, and Diners Club. We only accept payment by check or ACH debit for $5,988 prepayments for the Commercial plans. Mapbox Enterprise plans are invoiced through our Finance team.

If you do not have access to one of these cards, consider using a prepaid card instead. Prepaid cards are available from several vendors, including:

Still have a question about your invoices or statistics? Let us know!