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

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

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

{
  "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,
          "first_cpu_idle": 308,
          "time_to_interactive": 308,
          "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,
          "third_party_requests": 4,
          "third_party_size": 81203,
          "blocking_scripts": 5,
          "blocking_css": 1,
          "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"
            }
          ],
          "hero_metrics": [
          {
              "hero": "bg_img",
              "value": "8800"
          },
          {
              "hero": "biggest_img",
              "value": "6400"
          }
         ],
         "first_painted_hero": 13800,
         "last_painted_hero": 21400,
         "lighthouse_performance": 62,
         "lighthouse_pwa": 31,
         "lighthouse_accessibility": 69,
         "lighthouse_best_practice": 60,
         "lighthouse_seo": 100
        }
      ]
    }
  ]
}

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)
first_cpu_idle	Time to the page being interactive for the first time. (ms)
time_to_interactive	Time to the page being interactive and the CPU being quiet for at least 5s. (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)
third_party_requests	Number of requests made to third party domains.
third_party_size	Size of all requests made to third party domains.
blocking_scripts	Number of synchronous scripts that block rendering.
blocking_css	Number of CSS requests that block rendering.
har	URL to downloadable HAR file.
screen	URL to screen shot of loaded page.
custom_metrics	Any user timing marks found on the page.
hero_metrics	Rendering times for different elements in the viewport.
first_painted_hero	First of the hero times.
last_painted_hero	Last of the hero times.
lighthouse_performance	Google Lighthouse performance score.
lighthouse_pwa	Google Lighthouse PWA score.
lighthouse_accessibility	Google Lighthouse Accessibility score.
lighthouse_best_practice	Google Lighthouse Best Practice score.
lighthouse_seo	Google Lighthouse SEO score.

Get site details and settings

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

{
  "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

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

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

{
  "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

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

{
  "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,
      "first_cpu_idle": 308,
      "time_to_interactive": 308,
      "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,
      "third_party_requests": 4,
      "third_party_size": 81203,
      "blocking_scripts": 5,
      "blocking_css": 1,
      "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"
          }
      ],
      "hero_metrics": [
          {
              "hero": "bg_img",
              "value": "8800"
          },
          {
              "hero": "biggest_img",
              "value": "6400"
          }
      ],
      "first_painted_hero": 13800,
      "last_painted_hero": 21400,
      "lighthouse_performance": 62,
      "lighthouse_pwa": 31,
      "lighthouse_accessibility": 69,
      "lighthouse_best_practice": 60,
      "lighthouse_seo": 100
    }
  ]
}

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	7	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)
first_cpu_idle	Time to the page being interactive for the first time. (ms)
time_to_interactive	Time to the page being interactive and the CPU being quiet for at least 5s. (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)
third_party_requests	Number of requests made to third party domains.
third_party_size	Size of all requests made to third party domains.
blocking_scripts	Number of synchronous scripts that block rendering.
blocking_css	Number of CSS requests that block rendering.
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.
hero_metrics	Rendering times for different elements in the viewport.
first_painted_hero	First of the hero times.
last_painted_hero	Last of the hero times.
lighthouse_performance	Google Lighthouse performance score.
lighthouse_pwa	Google Lighthouse PWA score.
lighthouse_accessibility	Google Lighthouse Accessibility score.
lighthouse_best_practice	Google Lighthouse Best Practice score.
lighthouse_seo	Google Lighthouse SEO score.

Delete a URL

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

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

{
  "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,
  "first_cpu_idle": 3084,
  "time_to_interactive": 3084,
  "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,
  "third_party_requests": 4,
  "third_party_size": 81203,
  "blocking_scripts": 5,
  "blocking_css": 1,
  "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
    }
  ],
  "hero_metrics": [
      {
          "hero": "bg_img",
          "value": "8800"
      },
      {
          "hero": "biggest_img",
          "value": "6400"
      }
    ],
    "first_painted_hero": 13800,
    "last_painted_hero": 21400,
    "lighthouse_performance": 62,
    "lighthouse_pwa": 31,
    "lighthouse_accessibility": 69,
    "lighthouse_best_practice": 60,
    "lighthouse_seo": 100
}

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)
first_cpu_idle	Time to the page being interactive for the first time. (ms)
time_to_interactive	Time to the page being interactive and the CPU being quiet for at least 5s. (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)
third_party_requests	Number of requests made to third party domains.
third_party_size	Size of all requests made to third party domains.
blocking_scripts	Number of synchronous scripts that block rendering.
blocking_css	Number of CSS requests that block rendering.
har	URL to download HAR file with full waterfall details.
screen	URL to screen shot of the fully loaded page.
custom_metrics	Any user timing marks found on the page.
hero_metrics	Rendering times for different elements in the viewport.
first_painted_hero	First of the hero times.
last_painted_hero	Last of the hero times.
lighthouse_performance	Google Lighthouse performance score.
lighthouse_pwa	Google Lighthouse PWA score.
lighthouse_accessibility	Google Lighthouse Accessibility score.
lighthouse_best_practice	Google Lighthouse Best Practice score.
lighthouse_seo	Google Lighthouse SEO score.

Delete a test

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

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

{
  "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

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.

{
  "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

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

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

{
  "deploys": [
    {
      "deploy_id": 101809,
      "site_id": 29142,
      "timestamp": 1534917858,
      "note": "JS Blocking",
      "detail": "Release 14.2 with JS blocking"
    },
    {
      "deploy_id": 100891,
      "site_id": 29169,
      "timestamp": 153483345,
      "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.
timestamp	Unix timestamp of deploy.
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

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

{
  "deploy_id": 10,
  "site_id": 123,
  "timestamp": 1534917858,
  "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.
timestamp	Unix timestamp of 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.

Add a deploy

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.

{
  "deploy_id": 16,
  "site_id": 123,
  "timestamp": 1534917858,
  "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		The ID of the site you'd like to trigger a round of testing on.
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.
timestamp	Unix timestamp of 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

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

{
  "deploy_id": 10,
  "site_id": 123,
  "timestamp": 1534917858,
  "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.
timestamp	Unix timestamp of 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

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

{
  "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

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

{
  "teams":[
    {
      "team": "Guardian",
      "sites": [
        {
          "site": "Guardian Beta",
          "urls": [
            {
              "url": "http://www.theguardian.com/uk?view=mobile",
              "label": "Home"
            }
          ]
        },
        {
          "site": "Other Site",
          "urls": [
            {
              "url": "https://example.com/",
              "label": "URL with script and basic auth",
              "username": "guardian",
              "password": "test123",
              "script": "blockDomainsExcept\texample.com\nnavigate\t%URL%"
            }
          ]
        }
      ],
      "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

LUX

Export LUX Data

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

{
  "download_url":"https://s3.amazonaws.com/lux-exports.speedcurve.com/lux.gz"
}

Get LUX Export URL. Returns an S3 pre-signed URL for the specified LUX export file. The URL expires in 10 minutes. LUX export files are done on a daily basis and contain the data from 00:00:00 to 23:59:59 UTC. Files become available after 5am UTC. If you try to access the file between midnight and 5am you'll get a URL that returns an error.

This API endpoint is not enabled by default. In order to use this endpoint, please contact support@speedcurve.com to get this feature enabled.

Query Parameters

Parameter	Default	Description
date	""	The date parameter is a date string of the format "Ymd", eg, "20180128". It is optional and defaults to yesterday (the most recent export file).

HTTP Request

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

Response

Attribute	Description
download_url	Returns an S3 pre-signed URL for the specified LUX export file. The URL expires in 10 minutes.

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

30th Oct 2018

Add "First CPU Idle" and "Time To Interactive" metrics. Note that "First Interactive" is now deprecated and will be removed down the track.

4th Sept 2018

Add /lux/export endpoint for exporting raw LUX page views.

22nd Aug 2018

Add timestamps to /deploy endpoint.
Add add Lighthouse metrics.
Add hero rendering metrics.

24th Oct 2017

Added third party and blocking metrics.

25th Sept 2017

Added hero rendering times

1st May 2017

Add support for deleting sites, URLs, tests and notes.

24 Feb 2017

Add a list of all deploys to the /deploys endpoint.
Rename /deploy endpoint to /deploys for consistency.

9 Feb 2017

Removed median tests results from /sites endpoint by default. Can be re-enabled with median=1.

9 Jan 2017

Added "status" for any test results so errors vs successful tests are easier to determine.

31 Oct 2016

Added more detail to test data including bandwidth down/up, latency and packet loss along with custom metrics.

25 Oct 2016

Added new import/export endpoints that takes a JSON settings object and let's you update the basic settings for an account/team.

18 May 2016

Add site/{site_id} endpoint with site settings details.
Change "location" to "region" in returned JSON to match Settings naming.
Removed "statusboard" format option form /sites endpoint.
Added custom_metrics to urls/{url_id} endpoint.

23 Nov 2015

Added support for triggering a deploy on any site in an account/team.
Added support for site_id on Notes letting you add notes to any site.
Switched to note_id, deploy_id, site_id for clarity and more consistency.

18 Feb 2015

Added Deployment method to trigger additional rounds of testing for the main site in an account.

9 Jan 2015

Added Notes method to read and write notes to the main site in an account.

24 May 2014

Added support for multi-site accounts to the "urls" method.
Added more details to the median results for the "sites" method.

26 April 2014

Switch to HTTPS only
Extended Sites method to include multi-site accounts.

27 Mar 2014

Add 14 day median history to Sites method.

23 Mar 2014

Changed method names to plural and switched "user" to "sites".
Added Pagespeed
Added Speed Index