This add-on is operated by Runscope Inc

Debug, test and share your HTTP or REST backend service API calls.


Last Updated: 02 December 2013

Table of Contents

Runscope is an add-on for debugging, testing and sharing your HTTP or REST API calls.

Adding Runscope to an application provides:

  • Traffic Inspector: Inspect any HTTP API call with complete request and response data. Capturing requests is easy and works with any HTTP client library (like HTTParty, Requests, HttpClient, AFNetworking and more).
  • Request Editor: Our web-based HTTP request editor makes it easy to execute API calls without having to write any code. Start from scratch or use an existing request as a starting point, making it easy to tweak a failing request until it works.
  • Shared Requests: Having trouble with a particular API call and need another set of eyes to help out? Quickly create a shareable link to give to someone else to view any of your requests. Subscribers to a team plan can also privately share requests amongst team members.

Runscope is accessible via an API and has client libraries for Python, iOS/Objective-C, Ruby, and .NET.

Provisioning the add-on

Runscope can be attached to a Heroku application via the CLI:

$ heroku addons:add runscope
-----> Adding runscope to sharp-mountain-4005... done, v18 (free)

Once Runscope has been added a RUNSCOPE_BUCKET_KEY setting will be available in the app configuration. This can be confirmed using the heroku config:get command. You will use this key in the hostname of the Runscope URL you generate to indicate that you want that request to be stored in the associated bucket.

$ heroku config:get RUNSCOPE_BUCKET_KEY

Local setup

After provisioning the add-on it’s necessary to locally replicate the config vars so your development environment can operate against the service.

Though less portable it’s also possible to set local environment variables using export RUNSCOPE_BUCKET_KEY=bucket_key.

Use Foreman to configure, run and manage process types specified in your app’s Procfile. Foreman reads configuration variables from an .env file. Use the following command to add the RUNSCOPE_BUCKET_KEY values retrieved from heroku config to .env.

$ heroku config -s | grep RUNSCOPE_BUCKET_KEY >> .env
$ more .env

Credentials and other sensitive configuration values should not be committed to source-control. In Git exclude the .env file with: echo .env >> .gitignore.

Sending an HTTP request through Runscope

To create a Runscope hostname from any URL combine the hostname with your bucket key, change dots to dashes, and leave the path and query parameters unchanged.

Here’s an example:

https:// api . yourapihere . com /path/

Your Bucket Key:

Your Runscope URL:
https:// api - yourapihere - com - bucket_key . runscope . net /path/

Using with Rails 3.x

You can integrate Runscope with your Ruby on Rails applications by using the runscope-rb gem. Be sure to set the bucket key to the value of your RUNSCOPE_BUCKET_KEY config variable.

Using with Python/Django

You can integrate Runscope with Requests for Python using the official Runscope Adapter. You should set the bucket key to the value of your RUNSCOPE_BUCKET_KEY config variable.

Using Service Regions

Runscope operates servers in different regions around the world to help reduce the amount of time it takes to execute requests. If you’re on a paid Runscope plan, you can send requests to Runscope in any service region. Free plans are limited to our Northern Virginia region, which is located near Heroku’s US region. Learn more about using Runscope in alternate regions.

Runscope Dashboard

The Runscope Dashboard allows you to view the traffic you’ve sent through Runscope, execute HTTP requests from your browser, and create a publicly-available link that you can share with other people to view the data in a request and response. For more information on the features available within the Runscope dashboard, follow the links in the sidebar to the left.

Removing the add-on

Runscope can be removed via the CLI.

This will close your Runscope account and destroy all associated data. Please be careful!

$ heroku addons:remove runscope
-----> Removing runscope from sharp-mountain-4005... done, v20 (free)


All Runscope support and runtime issues should be submitted via on of the Heroku Support channels. Any non-support related issues or product feedback is welcome at

Any issues related to Runscope service are reported at Runscope Status.

Please also follow us on twitter, @runscope, for status and product announcements.