NAV
curl

SpeedCurve v1 API

The SpeedCurve v1 API is currently in beta and being actively developed. Please log any errors or issues you find with SpeedCurve support.

Refer to this documentation for the latest changes. Version “v1” of the API is mainly read (GET) only, allowing you to pull results out for your own dashboards and analysis.

Change Log

Getting Started

The SpeedCurve API is based on REST: it is comprised of resources with predictable urls and utilises standard HTTP features (like HTTP Basic Authentication, Response Codes and Methods). All requests, including errors, return JSON.

API Endpoint

The base URI for the V1 API is:

https://api.speedcurve.com/v1

API Key & Authentication

Basic Authentication

curl "https://api.speedcurve.com/v1/sites"
-u your-api-key:x

Basic Authentication over HTTPS is used to authenticate with the API. Your basic authentication username is your API key and the password can be set to anything. In our examples the API key is “your-api-key” and the password is “x”.

Your API key is available on the Admin > Teams page.

Sites

Get all sites

Request

curl "https://api.speedcurve.com/v1/sites"
-u your-api-key:x

Response

{
  "sites": [
    {
      "site_id": 123,
      "name": "Guardian",
      "urls":[
        {
           "url_id": 123,
           "url": "http://www.theguardian.com/"
        }
      ],
      "median":[
        {
          "test_id":"140325_WS_2V3",
          "timezone": "Pacific/Auckland",
          "day":"2014-03-26",
          "timestamp": 1448147927,
          "region": "us-west-1",
          "status": 0,
          "run": 2,
          "browser": "Google Chrome",
          "browser_version": "46.0.2490.86",
          "viewport_width": 768,
          "viewport_height": 1024,
          "pixel_ratio": 2,
          "bandwidth_down": 5000,
          "bandwidth_up": 1000,
          "bandwidth_latency": 28,
          "bandwidth_packet_loss_rate": 0,
          "byte": 130,
          "render": 421,
          "visually_complete": 420,
          "dom": 417,
          "loaded": 423,
          "size": 33695,
          "image_saving": 0,
          "requests": 6,
          "pagespeed": 89,
          "speedindex": 400,
          "html_requests": 1,
          "html_size": 6041,
          "css_requests": 2,
          "css_size": 6977,
          "js_requests": 2,
          "js_size": 41261,
          "image_requests": 3,
          "image_size": 27676,
          "font_requests": 0,
          "font_size": 0,
          "text_requests": 0,
          "text_size": 0,
          "flash_requests": 0,
          "flash_size": 0,
          "other_requests": 0,
          "other_size": 0,
          "har": "https://wpt.speedcurve.com/export.php?test=140325_WS_2V3",
          "screen": "https://wpt.speedcurve.com/getfile.php?test=140325_WS_2V3&file=2_screen.jpg",
          "custom_metrics": [
            {
              "mark": "speedcurve_js_top",
              "value": "1240"
            }
          ]
        }
      ]
    }
  ]
}

Retrieves all sites and monitored URL’s for an account/team and the median tests for a site across all templates/URL’s and regions.

Query Parameters

Parameter Default Description
median 0 Return median tests across all URLs for a site. Off by default. (0 = off, 1 = on)
days 14 Number of days of median tests to return. (Max: 365)

HTTP Request

GET https://api.speedcurve.com/v1/sites

Response

Attribute Description
sites List of sites associated with this account/team.
site_id ID of site which can then be used for deploys or adding notes.
name Name of the site.
urls List of URL’s associated with this site.
url_id ID of URL.
url URL associated with this site.
median Median test result for url’s grouped by site. Median is selected based on Speed Index which is the default for the SpeedCurve dashboards.
timezone Timezone of the account/team.
day Day of the median test result.
timestamp Unix timestamp of test result.
test WebPageTest ID of the median test result.
region AWS region that test was run in.
status Test result status. 0 = success and everything else is an error.
run Number of WebPageTest run that is used for this test. Median is based on Speed Index.
browser Browser name.
browser_version Browser version number.
byte Time to first byte in ms of the median result. Also known as Backend (ms)
render Time it start render which is extracted from the video of the page loading and is the first moment that a user see content appear on screen. (ms)
visually_complete Time to the viewport being visually complete. (ms)
dom Time to DOM complete browser event. Also known as Page Load (ms)
loaded Fully loaded time in ms of the median result. (ms)
size Total size of all assets. (bytes)
image_saving Number of bytes that could be saved if all images were compressed correctly. (bytes)
requests Total number of asset requested and downloaded by the page.
pagespeed Google PageSpeed Insights test score.
speedindex WebPagetest user experience score. Speed Index.
*_requests Total number of asset requested for a specific content type.
*_size Total size of assets for a specific content type. (bytes)
har URL to downloadable HAR file.
screen URL to screen shot of loaded page.

Get site details and settings

Request

curl "https://api.speedcurve.com/v1/sites/299"
-u your-api-key:x

Response

{
  "site": {
    "site_id": 299,
    "name": "Guardian Beta",
    "urls": [
      {
        "url_id": 906,
        "label": "home",
        "url": "http://www.theguardian.com/uk?view=mobile"
      },
      {
        "url_id": 907,
        "label": "section",
        "url": "http://www.theguardian.com/football?view=mobile"
      }
    ],
    "regions": [
      {
        "region_id": "eu-west-1"
      },
      {
        "region_id": "ap-southeast-2"
      }
    ],
    "browsers": [
      {
        "browser_id": "apple-ipad"
      },
      {
        "browser_id": "apple-iphone-5"
      },
      {
        "browser_id": "chrome"
      },
      {
        "browser_id": "internet-explorer-11"
      }
    ]
  }
}

Retrieves details and settings for a specific site. Setting details like region_id and browser_id can then be used to filter other endpoints.

HTTP Request

GET https://api.speedcurve.com/v1/sites/{site_id}

Response

Attribute Description
site_id ID of site which can then be used for deploys or adding notes.
name Name of the site.
urls List of URLs associated with this site.
url_id ID of URL.
label Label for the URL.
url URL associated with this site.
regions List of regions that the site is being monitored from.
region_id ID of region.
browsers List of browsers that the site is being tested with.
browser_id ID of browser.

Delete a site

Request

curl -X "DELETE" "https://api.speedcurve.com/v1/sites/299"
-u your-api-key:x

Deletes a site and all settings, test history and URLs associated with it.

HTTP Request

DELETE https://api.speedcurve.com/v1/sites/{site_id}

Urls

Get all URLs

Request

curl "https://api.speedcurve.com/v1/urls"
-u your-api-key:x

Response

{
  "sites": [
    {
      "site_id": 299,
      "name": "Guardian Beta",
      "urls": [
        {
          "url_id": 906,
          "url": "http://www.theguardian.com/uk?view=mobile",
          "label": "home"
        },
        {
          "url_id": 907,
          "url": "http://www.theguardian.com/football?view=mobile",
          "label": "section"
        }
      ]
    },
    {
      "site_id": 303,
      "name": "Huffington",
      "urls": [
        {
          "url_id": 920,
          "url": "http://www.huffingtonpost.com/",
          "label": "home"
        }
      ]
    }
  ]
}

Retrieves the metadata for all URLs across your sites.

HTTP Request

GET https://api.speedcurve.com/v1/urls

Response

Attribute Description
sites List of sites in your settings
site_id ID for a site
name Name of site.
urls List of URLs associated with this site.
url_id ID of URL.
label Label for the URL.
url URL associated with this site.

Get all tests for a URL

Request

curl "https://api.speedcurve.com/v1/urls/536"
-u your-api-key:x

Response

{
  "url_id": 123,
  "url": "http://www.theguardian.com/",
  "tests":[
    {
      "test_id":"140325_WS_2V3",
      "timezone": "Pacific/Auckland",
      "day":"2014-03-26",
      "timestamp": 1448147927,
      "region": "us-west-1",
      "status": 0,
      "run": 2,
      "browser": "Google Chrome",
      "browser_version": "46.0.2490.86",
      "viewport_width": 768,
      "viewport_height": 1024,
      "pixel_ratio": 2,
      "bandwidth_down": 5000,
      "bandwidth_up": 1000,
      "bandwidth_latency": 28,
      "bandwidth_packet_loss_rate": 0,
      "byte": 130,
      "render": 421,
      "visually_complete": 423,
      "dom": 417,
      "loaded": 423,
      "size": 33695,
      "image_saving": 0,
      "requests": 6,
      "pagespeed": 89,
      "speedindex": 400,
      "html_requests": 1,
      "html_size": 6041,
      "css_requests": 2,
      "css_size": 6977,
      "js_requests": 2,
      "js_size": 41261,
      "image_requests": 3,
      "image_size": 27676,
      "font_requests": 0,
      "font_size": 0,
      "text_requests": 0,
      "text_size": 0,
      "flash_requests": 0,
      "flash_size": 0,
      "other_requests": 0,
      "other_size": 0,
      "har": "https://wpt.speedcurve.com/export.php?test=140325_WS_2V3",
      "screen": "https://wpt.speedcurve.com/getfile.php?test=140325_WS_2V3&file=2_screen.jpg",
      "custom_metrics": [
          {
            "mark": "stylesheets_done",
            "value": "2907.186464"
          }
      ]
    }
  ]
}

Retrieves all the metadata for tests of a specific monitored URL.

Query Parameters

Parameter Default Description
browser All Filter tests to a specific browser. Get browser_id from sites/{site_id} endpoint.
region All Filter tests to a specific region. Get region_id from sites/{site_id} endpoint.
days 14 Number of days of tests (Max: 365).

HTTP Request

GET https://api.speedcurve.com/v1/urls/{url_id}?days=30&browser=chrome&region=us-west-1

Response

Attribute Description
test_id WebPageTest ID of the median test result.
url_id ID of URL.
url Monitored URL.
tests list of associated tests.
timezone Timezone of the account/team.
day Day of the median test result.
timestamp Unix timestamp of test result.
region AWS region that test was run in.
status Test result status. 0 = success and everything else is an error.
run Number of WebPageTest run that is used for this test. Median is based on Speed Index.
browser Browser name.
browser_version Browser version number.
byte Time to first byte in ms of the median result. Also known as Backend (ms)
render Time it start render which is extracted from the video of the page loading and is the first moment that a user see content appear on screen. (ms)
visually_complete Time to the viewport being visually complete. (ms)
dom Time to DOM complete browser event. Also known as Page Load (ms)
loaded Fully loaded time in ms of the median result. (ms)
size Total size of all assets. (bytes)
image_saving Number of bytes that could be saved if all images were compressed correctly. (bytes)
requests Total number of asset requested and downloaded by the page.
pagespeed Google PageSpeed Insights test score.
speedindex WebPagetest user experience score. Speed Index.
*_requests Total number of asset requested for a specific content type.
*_size Total size of assets for a specific content type. (bytes)
har URL to downloadable HAR file.
screen URL to screen shot of loaded page.
custom_metrics Any user timing marks and measures found on the URL.

Delete a URL

Request

curl -X "DELETE" "https://api.speedcurve.com/v1/urls/906"
-u your-api-key:x

Deletes a URL and any test history associated with it.

HTTP Request

DELETE https://api.speedcurve.com/v1/urls/{url_id}

Tests

Get a test

Request

curl "https://api.speedcurve.com/v1/tests/140317_BA_3W8"
-u your-api-key:x

Response

{
  "test_id": "170326_DF_b09ab842443d52381ce6971041100518",
  "url": "http://www.theguardian.com/uk/",
  "timezone": "America/New_York",
  "day": "2014-03-18",
  "timestamp": 1449505109,
  "region": "us-west-1",
  "status": 0,
  "run": 1,
  "browser": "Google Chrome",
  "browser_version": "33.0.1750.154",
  "viewport_width": 768,
  "viewport_height": 1024,
  "pixel_ratio": 2,
  "bandwidth_down": 5000,
  "bandwidth_up": 1000,
  "bandwidth_latency": 28,
  "bandwidth_packet_loss_rate": 0,
  "byte": 301,
  "render": 1604,
  "visually_complete": 2390,
  "dom": 2599,
  "loaded": 3216,
  "size": 537918,
  "image_saving": 37682,
  "requests": 37,
  "pagespeed": 83,
  "speedindex": 3017,
  "html_requests": 2,
  "html_size": 5311,
  "css_requests": 3,
  "css_size": 135438,
  "js_requests": 2,
  "js_size": 26243,
  "image_requests": 30,
  "image_size": 287149,
  "font_requests": 0,
  "font_size": 0,
  "text_requests": 0,
  "text_size": 0,
  "flash_requests": 0,
  "flash_size": 0,
  "other_requests": 0,
  "other_size": 0,
  "har": "https://wpt.speedcurve.com/export.php?test=140317_N9_3W9",
  "screen": "https://wpt.speedcurve.com/results/14/03/17/N9/3W9/1_screen.jpg",
  "custom_metrics": [
    {
      "mark": "speedcurve_js_top",
      "value": 1240
    }
  ]
}

Retrieves all the details available for a specific test.

HTTP Request

GET https://api.speedcurve.com/v1/tests/{test_id}

Response

Attribute Description
test_id Id for the test files.
url URL of the page tested.
timezone Timezone of the account/team.
day Date of the test. New tests begin at UTC/GMT +12 hours.
timestamp Unix timestamp of test result.
region AWS datacenter the test agent was located in.
status Test result status. 0 = success and everything else is an error.
run The median browser testing run used for the results.
browser_name Browser name.
browser_version Browser version number.
byte Time to first HTML byte. Indicative of server processing time and network latency. Also know as Backend. (ms)
render Time to start render which is extracted from the video of the page loading and is the first moment that a user see content appear on screen. (ms)
visually_complete Time to the viewport being visually complete. (ms)
dom Time to DOM complete browser event. Also known as Page Load. (ms)
loaded Time to the page being fully loaded. (ms)
size Total size of all assets. (bytes)
image_saving Saving that could be made by convering Jpegs to progressive 85 quality and stripping metadata from PNG’s. (bytes)
requests Total number of asset requested and downloaded by the page.
pagespeed Google PageSpeed Insights test score.
speedindex WebPagetest user experience score. Speed Index.
*_requests Total number of asset requested for a specific content type.
*_size Total size of assets for a specific content type. (bytes)
har URL to download HAR file with full waterfall details.
screen URL to screen shot of the fully loaded page.

Delete a test

Request

curl -X "DELETE" "https://api.speedcurve.com/v1/tests/170326_DF_b09ab842443d52381ce6971041100518"
-u your-api-key:x

Deletes a single test result.

HTTP Request

DELETE https://api.speedcurve.com/v1/tests/{test_id}

Notes

Get all notes

Request

curl "https://api.speedcurve.com/v1/notes"
-u your-api-key:x

Response

{
  "notes": [
    {
      "note_id": 1912,
      "site_id": 123,
      "timestamp": 1420745970,
      "note": "I'm a note!",
      "detail": "I'm a longer note with way more detail."
    },
    {
      "note_id": 1911,
      "site_id": 123,
      "timestamp": 1420745966,
      "note": "New responsive site goes live!",
      "detail": ""
    }
  ]
}

Gets all the notes for the main site in a users account.

Query Parameters

None.

HTTP Request

GET https://api.speedcurve.com/v1/notes

Response

Attribute Description
note_id ID of the note.
site_id ID of site that this note is associated with.
timestamp UTC Unix timestamp.
note Short note content to display on graphs.
detail Longer note content to provide more context when a user interacts with a note.

Add a note

Request

curl "https://api.speedcurve.com/v1/notes"
-u your-api-key:x
--request POST
--data timestamp=now
--data site_id=123
--data note=I%27m%20a%20note!
--data detail=I%27m%20a%20longer%20note%20with%20way%20more%20detail.

Response

{
  "note_id": 1912,
  "site_id": 123,
  "timestamp": 1420745970,
  "note": "I'm a note!",
  "detail": "I'm a longer note with way more detail."
}

Add a note to one of the sites within your account/team.

HTTP Request

POST https://api.speedcurve.com/v1/notes

Query Parameters

Parameter Default Description
timestamp now Either a UTC Unix Timestamp or “now”. Options: (now, unix timestamp).
site_id First site in account/team ID of site to add note to. If no ID provided then note is added to the first site in the account/team.
note Short URL encoded note to display globally across all graphs for the main site. (Max: 255 characters).
detail Optional note detail to display if people want more context.

Response

Attribute Description
note_id ID of the note.
site_id ID of associated site.
timestamp UTC Unix timestamp.
note Short note content to display on graphs.
detail Longer note content to provide more context when a user interacts with a note.

Delete a note

Request

curl -X "DELETE" "https://api.speedcurve.com/v1/notes/1912"
-u your-api-key:x

Delete a note.

HTTP Request

DELETE https://api.speedcurve.com/v1/notes/{note_id}

Deploys

All deploys

Request

curl "https://api.speedcurve.com/v1/deploys"
-u your-api-key:x

Response

{
  "deploys": [
    {
      "deploy_id": 101809,
      "site_id": 29142,
      "note": "JS Blocking",
      "detail": "Release 14.2 with JS blocking"
    },
    {
      "deploy_id": 100891,
      "site_id": 29169,
      "note": "All mobile locations",
      "detail": ""
    }
  ]
}

Gets all deployments.

Query Parameters

Parameter Default Description
site_id All Filter deploys to a specific site. Get site_id from sites/ endpoint.

HTTP Request

GET https://api.speedcurve.com/v1/deploys

Response

Attribute Description
deploy_id ID of the deployment.
site_id ID of site the deploy has been added to.
note Short note content to display on graphs.
detail Longer note content to provide more context when a user interacts with a note.

Latest deploy

Request

curl "https://api.speedcurve.com/v1/deploys/latest"
-u your-api-key:x

Response

{
  "deploy_id": 10,
  "site_id": 123,
  "status": "completed",
  "tests-completed": [
    {
      "test": "150217_Z2_CJ7",
      "browser": "safari",
      "region": "us-west-1",
      "template": 84
    },{
      "test": "150217_6X_CJ8",
      "browser": "ie 11",
      "region": "us-west-1",
      "template": 85
    }
  ],
  "tests-remaining": null,
  "note": "#465 Responsive",
  "detail": "Deploy #465, awesome new responsive site live!"
}

Gets details and status of testing for the latest deployment.

Query Parameters

None.

HTTP Request

GET https://api.speedcurve.com/v1/deploys/latest

Response

Attribute Description
deploy_id ID of the deployment.
site_id ID of site the deploy has been added to.
status Status of testing.
test-remaining Remaining tests waiting to be tested.
test-completed Tests completed.
note Short note content to display on graphs.
detail Longer note content to provide more context when a user interacts with a note.

Add a deploy

Request

curl "https://api.speedcurve.com/v1/deploys"
-u your-api-key:x
--request POST
--data site_id=123
--data note=I%27m%20a%20note!
--data detail=I%27m%20a%20longer%20note%20with%20way%20more%20detail.

Response

{
  "deploy_id": 16,
  "site_id": 123,
  "status": "success",
  "message": "A deployment has been added",
  "info": [
    {
      "test": "150217_Z2_CJ7",
      "browser": "safari",
      "region": "us-west-1",
      "template": 84
    },{
      "test": "150217_6X_CJ8",
      "browser": "ie 11",
      "region": "us-west-1",
      "template": 85
    }
  ],
  "tests-requested": 2
}

Add a deployment and trigger an additional round of testing for one of the sites in your account/team. A note is also automatically added to your graphs.

Depending on the number of templates/URLs you have it can take a few min to complete a round of tests across your site so we don’t recommend making this a dependency for deployments. Rather you should trigger a post deployment request to the API to trigger a round of testing once your release is live. We use the “note” as a key and people usually add the version number of a deployment as the note. So if you push a new deployment while there’s one in progress we check the “note” that’s been sent through. If the “note” is the same we return an error (403) assuming that it’s a duplicate request. If the note is different we assume it’s a new deployment, reset any tests in progress and delete the previous half complete deployment.

HTTP Request

POST https://api.speedcurve.com/v1/deploys

Query Parameters

Parameter Default Description
site_id First site in account/team The ID of the site you’d like to trigger a round of testing on. If no site_id then the deployment is added to the first site in the account/team.
note Short URL encoded note to display globally across all graphs for the main site. (Max: 255 characters).
detail Optional URL encoded note detail to display if people want more context.

Response

Attribute Description
deploy_id ID of deployment.
site_id ID of the site associated with the deploy.
status Status of deployment.
message Status message.
info Info about the tests added for this deployment.
tests-requested Number of tests added to the queue.

Get a deploy

Request

curl "https://api.speedcurve.com/v1/deploys/1234"
-u your-api-key:x

Response

{
  "deploy_id": 10,
  "site_id": 123,
  "status": "completed",
  "tests-completed": [
    {
      "test": "150217_Z2_CJ7",
      "browser": "safari",
      "region": "us-west-1",
      "template": 84
    },{
      "test": "150217_6X_CJ8",
      "browser": "ie 11",
      "region": "us-west-1",
      "template": 85
    }
  ],
  "tests-remaining": null,
  "note": "#465 Responsive",
  "detail": "Deploy #465, awesome new responsive site live!"
}

Get the details for a particular deployment.

HTTP Request

GET https://api.speedcurve.com/v1/deploys/{deploy_id}

Response

Attribute Description
deploy_id ID of the deployment.
site_id ID of the site associated with the deploy.
status Status of testing.
test-remaining Remaining tests waiting to be tested.
test-completed Tests completed.
note Short note content to display on graphs.
detail Longer note content to provide more context when a user interacts with a note.

Settings

Import Settings

Request

curl "https://api.speedcurve.com/v1/import"
-u your-api-key:x
--request POST
--data mode=merge
--data data={ JSON settings object }

Response

{
  "status":"success",
  "message":"'Guardian' was updated."
}

You can update the settings in your account/team by importing JSON settings. Bulk site settings import shows the JSON schema required which you can use to add new sites, browsers, regions and test times or update existing URLs.

Using this endpoint you can keep all your settings in version control or programmatically update specific URLs as often as you like.

HTTP Request

POST https://api.speedcurve.com/v1/import

Query Parameters

Parameter Default Description
mode (merge,replace) “Merge” - Leaves existing settings in place and applies any changes found in the new JSON. To update an existing URL use the “url_to_update” option in the JSON schema. “Replace” - Warning: deletes ALL the existing settings for ALL sites first and then adds the new JSON. Any history for URLs, performance budgets and notes will be deleted. Only use this mode if you want to start from a clean slate with an empty account.
data JSON settings object

Response

Attribute Description
status Status of import.
message Status message.

Export Settings

Request

curl "https://api.speedcurve.com/v1/export"
-u your-api-key:x

Response

{
  "teams":[
    {
      "team": "Guardian",
      "sites": [
        {
          "site": "Guardian Beta",
          "urls": [
            {
              "url": "http://www.theguardian.com/uk?view=mobile",
              "label": "Home"
            }
          ]
        }
      ],
      "site_settings": 
        {
          "regions": [
            "US West Coast"
          ],
          "browsers": [
            "Apple iPad",
            {
              "name": "Apple iPad Landscape",
              "browser": "Chrome",
              "viewport": {
                  "width": 1024,
                  "height": 768,
                  "devicePixelRatio": 2
              },
              "bandwidthDown_KBps": 5000,
              "bandwidthUp_KBps": 1000,
              "latency_Ms": 28
          },
          "Apple iPhone 5",
          {
              "name": "Apple iPhone 5 Landscape",
              "browser": "Chrome",
              "viewport": {
                  "width": 568,
                  "height": 320,
                  "devicePixelRatio": 2
              },
              "bandwidthDown_KBps": 1600,
              "bandwidthUp_KBps": 768,
              "latency_Ms": 300
          },
          "Chrome"
      ],
      "times": [
          "16:00"
      ]
      }
    }
  ]
}

Returns the current account/team settings in the JSON import format. You can then edit and import these settings using the “merge” mode to make changes. Warning: Not all settings like budgets, notes, domains etc are yet supported by the export/import endpoints. If you do an export and then import the same file using the “replace” mode you will lose any of the non supported settings. Always use the “merge” mode when importing unless you want to delete all settings in your account and start from scratch.

HTTP Request

GET https://api.speedcurve.com/v1/export

Response

Attribute Description
JSON JSON object that represents your account/team settings

Errors

The SpeedCurve API uses the following error codes:

Error Code Description
400 Bad Request – Request cannot be fulfilled due to bad syntax.
401 Unauthorized – Invalid API key.
403 Forbidden – Insufficient privileges to perform this action.
404 Not Found – The requested resource was not found.
500 Internal Server Error – We had a problem with our server. Try again later.
503 Service Unavailable – We’re temporarily offline for maintenance. Please try again later.

Change Log

1st May 2017

24 Feb 2017

9 Feb 2017

9 Jan 2017

31 Oct 2016

25 Oct 2016

18 May 2016

23 Nov 2015

18 Feb 2015

9 Jan 2015

24 May 2014

26 April 2014

27 Mar 2014

23 Mar 2014