Ready to start talking to the Meta Smoke API? This page gives an introduction on how to get started with SmokeAPI.

First, you need to:

Basic Data Retrieval

Retrieving data is very simple. First, though, you will need an API Key. This key will be used every place you see the variable your_api_key.

Note: This is an API key. It is a unique identifier for your application. It’s not a disaster if you end up sharing it with other people unintentionally, but generally try to keep it protected. When you start making use of write capabilities, you’ll be issued with API tokens that provide authorization on an app-user-pair basis; these tokens are sensitive information and should be protected no matter what.

First, import the SmokeAPI module:

>>> from smokeapi import SmokeAPI

Now we want to retrieve a list of posts that have been marked as “Not an Answer” by users:

>>> SMOKE = SmokeAPI('your_api_key')
>>> posts = SMOKE.fetch('posts/feedback', type="naa-")

This will return the 500 most recent posts that have been classified as “Not an Answer”. The value passed to fetch is an end point defined in the MetaSmoke API Documentation.

If you are looking for more information on how to tailor the results of your queries. Take a look at the Advanced Usage examples.

Change number of results

By default, SmokeAPI will return up to 500 items in a single call. It may be less than this, if there are less than 500 items to return.

The number of results can be modified by changing the per_page and max_pages values. These are multiplied together to get the maximum total number of results. The API paginates the results and SmokeAPI recombines those pages into a single result.

The number of API calls that are made is dependant on the max_pages value. This will be the maximum number of calls that is made for this particular request.

All of these changes to per_page and max_pages need to occur before calls to fetch or send_data.

Let’s walk through a few examples:

>>> SMOKE.per_page = 10
>>> SMOKE.max_pages = 10

This will return up to 100 results. However, it will hit the API up to 10 times.

>>> SMOKE.per_page = 100
>>> SMOKE.max_pages = 1

This will result up to 100 results as well, but it will only hit the API one time.

MetaSmoke limits the number of results per page to 100. If you want more than 100 results, you need to increase the max_pages.

>>> SMOKE.per_page = 100
>>> SMOKE.max_pages = 2

This will return up to 200 results and hit the API up to twice.

Getting exact number of results

If you want a specific number of results, but no more than that, you need to perform some manipulations of these two values.

>>> SMOKE.per_page = 50
>>> SMOKE.max_pages = 3

This will return up to 150 results. It will also hit the API 3 times to get these results. You can save an API hit by changing the values to:

>>> SMOKE.per_page = 75
>>> SMOKE.max_pages = 2

This will also return up to 150 results, but do so in only 2 API hits.

Note: Each “page” in an API call can have up to 100 results. In the first scenario, above, we are “wasting” 150 results because we only allow each page 50 results. In the second scenario, we are wasting 50 results. If you do not need an exact number of results, it is more efficient - number of API calls-wise - to set the per_page to 100 and return the highest number of results per page that the system allows.


SmokeAPI will throw an error if the MetaSmoke API returns an error. This can be caught in an exception block by catching smokeapi.SmokeAPIError. The exception has several values available to help troubleshoot the underlying issue:

except smokeapi.SmokeAPIError as e:
    print("   Error URL: {}".format(e.url))
    print("   Error Code: {}".format(e.error_code))
    print("   Error Name: {}".format(e.error_name))
    print("   Error Message: {}".format(e.error_message))

This will print out the URL that was being accessed, the error code that the API returns, the error name the API returns and the error message the API returns. Using these values, it should be possible to determine the cause of the error.