Error & Crash Reporting API

The Raygun API is REST-oriented and uses JSON for all operations. You can manually publish errors to Raygun using this interface, or use it to create your own provider. All calls are made over HTTPS.

API Endpoint



The header must contain "X-ApiKey" with a value that is a valid Raygun Crash Reporting API key (available under Crash Reporting - Application Settings).

URI Summary

Crash Reporting error payloads

POST https://api.raygun.com/entries

The body of the message should be JSON with the following structure:

	// Date and time that the error occurred in ISO-8601 format
	"occurredOn": "2015-09-08T01:55:28Z",
	"details": {
		// The name of machine this error occurred on
		"machineName": "ServerMachine1",
		// Client defined error grouping key. Must be 1-100 chars, ideally the result of a hash function e.g MD5
		"groupingKey": "ErrorGroup",
		// The version number of your application.
		"version": "",
		// Information about the client library you are using for talking to the Raygun API
		"client": {
			// Name of the library
			"name": "Example Raygun Client",
			// Version of the library
			"version": "",
			// URL where the client can be downloaded or viewed
			"clientUrl": "https://raygun.com/docs/integrations/api"
		// Information about the error itself
		"error": {
			// The error that caused the outer error.
			// Has all the same properties as the "error" object that contains it.
			"innerError": {},
			// Data contained in the error object
			"data": {
				"example": 5
			// The name of the error
			"className": "ErrorClass",
			// The error message
			"message": "An error occurred",
			// The collection of stack traces.
			// The first one in the list should be the highest on the stack
			"stackTrace": [
				// The line number of this stack frame
				"lineNumber": 55,
				// The name of the class this stack frame is in
				"className": "BrokenService",
				// The column of the file that this stack frame is in
				"columnNumber": 23,
				// The name of the file this stack frame is in
				"fileName": "BrokenService.cs",
				// The name of the method this stack frame is in
				"methodName": "BreakEverything()"
		// Information about the environment at the time of the error.
		// Each of these properties are optional
		"environment": {
			// The number of processors in the machine
			"processorCount": 4,
			// The version of the operating system this app is running on
			"osVersion": "Windows 10",
			// The width of the window
			"windowBoundsWidth": 2560,
			// The height of the window
			"windowBoundsHeight": 1440,
			// The width of the browser window
			"browser-Width": 2560,
			// The height of the browser window
			"browser-Height": 1440,
			// The width of the screen
			"screen-Width": 2560,
			// The height of the screen
			"screen-Height": 1440,
			// The scale of the screen
			"resolutionScale": 1.0,
			// Color depth of the screen
			"color-Depth": 24,
			// The orientation of the screen
			"currentOrientation": "Landscape",
			// The type of CPU in the machine
			"cpu": "Intel(R) Core(TM) i5-2500 CPU @ 3.30GHz",
			"packageVersion": "package version",
			// CPU architecture (ARMv8, AMD64, etc)
			"architecture": "ARMv7-A",
			// Device manufacturer
			"deviceManufacturer": "Nokia",
			// Device model
			"model": "Lumia 920",
			// Total RAM in MB
			"totalPhysicalMemory": 1024,
			// Available RAM in MB
			"availablePhysicalMemory": number,
			// Total Virtual Memory in MB - RAM plus swap space
			"totalVirtualMemory": number,
			// Available Virtual Memory in MB
			"availableVirtualMemory": number,
			// Free disk space in GB
			"diskSpaceFree": [50000.52, 2000.104],
			// Name of the device (phone name for instance)
			"deviceName": "Nexus 7",
			// Locale setting of the system
			"locale": "en-nz",
			// Number of hours offset from UTC
			"utcOffset": -12,
			// The browser manufacturer
			"browser": "Mozilla",
			// The browser name
			"browserName": "Netscape",
			// The full user agent string
			"browser-Version": "5.0 (Windows NT 6.3; WOW64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/39.0.2171.65 Safari/537.36",
			// OS Name
			"platform": "Win32"
		// Tags that should be applied to the error
		// These will be searchable and filterable on the dashboard.
		"tags": ["tag1", "tag 2", "tag-3"],
		// Any custom data you would like to attach to this error instance.
		// You can search on data entered here.
		"userCustomData": {
			"domain": "WORKPLACE",
			"area": "51"
		// Information about the HTTP request being processed when the error occurred.
		// Only useful in a web environment obviously.
		"request": {
			// The hostName portion of the URL being requested.
			"hostName": "https://raygun.io",
			// The path portion of the URL being requested
			"url": "/docs/integrations/api",
			// The HTTP method used to request the URL (GET, POST, PUT, etc)
			"httpMethod": "POST",
			// The IP address of the client that initiated the request
			"iPAddress": "",
			// The query string portion of the URL
			"queryString": {
				"q": "searchParams"
			// The form parameters sent through with the request. Not form encoded.
			"form": {
				"firstName": "Example",
				"lastName": "Person",
				"newsletter": true
			// The HTTP Headers sent as part of the request
			"headers": {
				"Referer": "www.google.com",
				"Host": "raygun.io"
			// The raw request body. Don't include form values here.
			// See the notes for more information
			"rawData": "{\"Test\": 5}"
		// Information about the response that will be sent back to the client.
		"response": {
			// The HTTP status code that will be sent back to the client
			"statusCode": 500 
		// Information about the user that caused the error
		"user": {
			// Unique identifier for the user
			"identifier": "123456789",
			// Flag indicating if the user is anonymous or not
			"isAnonymous": false,
			// User's email address
			"email": "test@example.com",
			// User's full name
			"fullName": "Test User",
			// User's first name (what you would use if you were emailing them - "Hi {{firstName}}, ...")
			"firstName": "Test",
			// Device unique identifier. Useful if sending errors from a mobile device.
			"uuid": "783491e1-d4a9-46bc-9fde-9b1dd9ef6c6e"
		// A trail of breadcrumbs leading up to this error
		"breadcrumbs": [{
			// Milliseconds since the Unix Epoch (required)
			"timeStamp": 1504799959639,
			// The display level of the message (valid values are Debug, Info, Warning, Error)
			"level": "info",
			// The type of message (valid values are manual, navigation, click-event, request, console)
			"type": "navigation",
			// Any value to categorize your messages
			"category": "checkout",
			// The message you want to record for this breadcrumb
			"message": "User navigated to the shopping cart",
			// If relevant, a class name from where the breadcrumb was recorded
			"className": "ShoppingCart",
			// If relevant, a method name from where the breadcrumb was recorded
			"methodName": "ViewBasket",
			// If relevant, a line number from where the breadcrumb was recorded
			"lineNumber": 156,
			// Any custom data you want to record about application state when the breadcrumb was recorded
			"customData": { "from": "/category/product/123", "to": "/cart/view" }

HTTP Status Codes

202 OK - Message accepted.

400 Bad message - could not parse the provided JSON. Check all fields are present, especially both occurredOn (ISO 8601 DateTime) and details { } at the top level.

403 Invalid API Key - The value specified in the header X-ApiKey did not match with a user.

413 Request entity too large - The maximum size of a JSON payload is 128KB.

429 Too Many Requests - Plan limit exceeded for month or plan expired


  • OccurredOn must be present, and is a DateTime string in the ISO 8601 format, in the UTC timezone. This is of the format: YYYY-MM-DDTHH:MM:SSZ

  • The maximum size of the body is 128KB. Payloads larger than this will be discarded.
  • For the field details.request.form, we request that you truncate the names and values to 256 characters each. For rawData, this should be truncated to 4096 bytes.

  • rawData is to be set in the case where the method is non-GET, and the Content-Type is not text/html and not application/x-www-form-urlencoded.

  • There must be at least one details.error, and its stacktrace must have its linenumber set. The other fields can be empty.

  • details.request.form should be the raw form data available from a request-type object when the HTTP method is 'POST' and the Content-Type is 'application/x-www-form-urlencoded'.

  • For the details.environment fields where that data is unavailable from your language, framework or environment, these can safely be absent from the payload (or set to null).

  • User: identifier should be a string representation of the currently logged in user - something that uniquely identifies them in your app. If you set any user properties, you should at least set this one.

  • User: isAnonymous should be set to true if the user is not actually logged in to your app. This is to separate them from the "user info not provided" case.

  • User: uuid should be a device dependent identifier - most mobile device frameworks will give you an identifier of some sort to use here.

Change log

  • 7th Sep 2017 - Added breadcrumb section to documentation
  • 20th Feb 2016 - Updated API endpoint to api.raygun.com from api.raygun.io
  • 28th May 2015 - Add more information about user object. Remove old context object as context.identifier has been rolled into user.uuid.
  • 6th November 2013 - Removed request.httpStatusCode and added response.statusCode.



Webhooks allow you to notify external systems that Raygun doesn't currently support when:

When an error or crash occurs for a particular event type, we will post a JSON payload to the URL you specify. This is configured on a per-app basis, so you can set different URLs to be sent webhook notifications for each application.

To do this, open an application in Raygun and go to Integrations from the left-hand side menu. On the Integrations page, click the Webhook button.

From that page, you can specify the endpoint the webhook will be delivered to, and enable/disable it.

Available events

When an error occurs

Every time an error notification arrives from your app for a particular event type, the webhook will be fired. 

The body of the POST is JSON, and will look like the following if the notification is of the NewErrorOccurred or ErrorReoccurred type:

  "error": {
    "instance": {
      "tags": ["test", "error-page", "v1.0.1", "env:staging"],
      "affectedUser": {
        "Identifier": "a9b7d84a-c0d3-4e7e-9ded-1ec13d033846",
        "IsAnonymous": true,
        "UUID": "a9b7d84a-c0d3-4e7e-9ded-1ec13d033846" 
      "customData": {
        "pageName": "Error Page",
        "userLoggedIn": true
  "application": {
    "name":"application name",

Alternatively, if the error is of any other type it will look like the payload below: 

  "error": {
  "application": {
    "name":"application name",

Error Notification Event types

  • NewErrorOccurred [Contains error instance information]
  • ErrorReoccurred [Contains error instance information]
  • OneMinuteFollowUp
  • FiveMinuteFollowUp
  • TenMinuteFollowUp
  • ThirtyMinuteFollowUp
  • HourlyFollowUp

Note: Follow up events are dispatched when errors are still seen after the set period of time. 

Status changes on an error group

The body of the POST is JSON, and will look like the following if the notification is of the StatusChanged type:

  "error": {
    "description":"Emma marked error Script Error as Ignored",
    "message": "Script Error",
    "user":"Emma Cat"
  "application": {
    "name":"Best App",

Error group is assigned to a user

The body of the POST is JSON, and will look like the following if the notification is of the AssignedToUser type:

  "error": {
    "description":"Error Script Error was assigned to Kyle by Amy",
    "message": "Script Error",
    "assignedTo":"Kyle Kenny"
    "user":"Amy Loondon"
  "application": {
    "name":"application name",

A comment is added to an error group

The body of the POST is JSON, and will look like the following if the notification is of the CommentAdded type:

  "error": {
    "description":"Anita left a comment on error Script Error, 'Ignoring these errors'",
    "message": "Script Error",
    "comment":"Ignoring these errors",
    "user":"Anita Peacock"
  "application": {
    "name":"application name",

If you'd like to see a particular webhook for an event added, contact us or add a feature request from within Raygun.

Documentation missing?

If we don't have documentation about your desired topic, send us a message and we'll create it for you.