> For the complete documentation index, see [llms.txt](https://docs.plumvoice.com/insight/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.plumvoice.com/insight/api/survey-response-reporting.md).

# Survey Response Reporting

**Locating your report\_id**: This method can only be run on saved reports. Once you save your report you can visit the [View Survey Visits page](/insight/reporting/survey-visits.md), on which you'll see at the top a section labeled “Reporting API URL.” This will be the full URL you will use for survey response reporting via the API.

## Survey Response Reporting

<mark style="color:blue;">`GET`</mark> `https://insight.plumvoice.com/api/report/{report_id}`

This method allows you to fetch CSV exports of your saved survey reports programmatically (or through your browser, authenticating via http basic). There are a number of optional parameters supplied which will allow for you to paginate responses when working with very large data sets.

#### Path Parameters

| Name       | Type    | Description                            |
| ---------- | ------- | -------------------------------------- |
| report\_id | integer | The `report_id` for your saved report. |

#### Headers

| Name         | Type   | Description                       |
| ------------ | ------ | --------------------------------- |
| content-type | string | application/x-www-form-urlencoded |

#### Request Body

| Name             | Type    | Description                                                                                                                                                                                                                                                         |
| ---------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| start\_timestamp | integer | Unix timestamp to filter your survey responses to a specific date range.                                                                                                                                                                                            |
| end\_timestamp   | integer | Unix timestamp to filter your survey responses to a specific date range.                                                                                                                                                                                            |
| offset           | integer | Offset when querying for a row range. The offset will indicate at which row in the result set to begin including rows in the response csv. If you set an offset of 25, the first 25 rows will be ignored and row 26 will be the first row included in the response. |
| limit            | integer | Limit the number of rows returned. The limit must be between 1 and 10,000. If no limit is supplied, the limit will be 500.                                                                                                                                          |

{% tabs %}
{% tab title="200 Along with having the new report created in CSV format at 'reports/todays\_report.csv', running the above script with proper credentials produces the following output. The returned header values indicate the following: 1.) the request implicitly started at offset 0 (no offset specified, so the default was applied); 2.) the limit of 10 was applied, as supplied in the query string parameters; 3.) we received 10 rows in our response body; 4.) there were 12 total rows available for the report." %}

```
HTTP/1.1 200 OK
Date: Thu, 22 Sep 2016 18:41:49 GMT
Server: Apache/2.2.29 (Unix) mod_ssl/2.2.29 OpenSSL/1.0.2d PHP/5.4.45
X-Powered-By: PHP/5.4.45
Content-Disposition: attachment; filename=report.csv
X-Plum-Total-Rows: 12
X-Plum-Returned-Rows: 10
X-Plum-Row-Offset: 0
X-Plum-Row-Limit: 10
Content-Length: 941
Content-Type: text/csv; charset=utf-8


"Survey ID","Survey Name","Visit Type","Caller ID/IP Address","Phone Number",Start,End,Completed,"Was this information helpful?","What is your favorite decimal number?"
19571,"test reporting api",web,192.168.1.1,NA,1473861379,1473861390,1,1,55.5
19571,"test reporting api",web,192.168.1.1,NA,1473861348,1473861376,1,0,3
19571,"test reporting api",web,192.168.1.1,NA,1473861309,1473861318,1,0,67.5
19571,"test reporting api",web,192.168.1.1,NA,1473861298,1473861305,1,0,87.8
19571,"test reporting api",web,192.168.1.1,NA,1473861289,1473861294,1,1,78.8
19571,"test reporting api",web,192.168.1.1,NA,1473861279,1473861286,1,1,5656.66
19571,"test reporting api",web,192.168.1.1,NA,1473861254,1473861261,1,1,45.76
19571,"test reporting api",web,192.168.1.1,NA,1473861234,1473861251,1,1,97.6
19571,"test reporting api",web,192.168.1.1,NA,1473861223,1473861230,1,1,56.45
19571,"test reporting api",web,192.168.1.1,NA,1473861206,1473861212,1,0,45.5
```

{% endtab %}

{% tab title="400 Example: the report\_id supplied was not valid." %}
{% tabs %}
{% tab title="JSON" %}

```javascript
{"error":"You do not have permission to access this report"}
```

{% endtab %}

{% tab title="XML" %}

```markup
<?xml version="1.0"?>
<result>
  <error>You do not have permission to access this report</error>
</result>
```

{% endtab %}
{% endtabs %}
{% endtab %}
{% endtabs %}

{% hint style="info" %}
**NOTE**: Results will be ordered in descending order by start time, so the most recent response will always be first. The `start_timestamp` and `end_timestamp` parameters are dependent on one another; if you supply one, you must supply the other. By default, if no parameters are supplied, the response will contain the full date range of survey responses with an offset of 0 and limit of 500, returning up to 500 of the most recent survey visits.
{% endhint %}

## **Possible Response Codes**

* **200**: success
* **400**: parameters supplied were not valid
* **401**: authentication headers invalid or the account is inactive
* **403**: you do not own the report
* **404**: the saved report was not found or no rows were matched for the report
* **405**: invalid HTTP method supplied (only GET allowed)
* **500**: server error

### **Response Notes**

**Headers**

Since the payload of a successful request will be the csv data for the report, we've included a number of headers that will act as metadata related to the returned data and the overall data for the report. The following headers will be included:

| Header Name          | Type | Description                                                             |
| -------------------- | ---- | ----------------------------------------------------------------------- |
| X-Plum-Total-Rows    | int  | This value indicates the total number of rows that matched the query.   |
| X-Plum-Returned-Rows | int  | This value indicates the total number of rows returned in the response. |
| X-Plum-Row-Offset    | int  | This value indicates the offset applied to the current response.        |
| X-Plum-Row-Limit     | int  | This value indicates the limit applied to the current response.         |

These headers should allow you to paginate your requests, if you're working with a very large data set.

**Structure**

The return structure differs based on whether rows were matched or not.

A successful response, one in which rows were matched, will *always* return an http code of 200 and the body of the response will be in text/CSV format, which will be the raw output of your CSV report. A sample of a successful response would be the following:

```
"Survey ID","Survey Name","Visit Type","Caller ID/IP Address","Phone Number",Start,End,Completed,"Was this information helpful?","What is your favorite decimal number?"
19571,"test reporting api",web,192.168.1.1,NA,1473861379,1473861390,1,1,55.5
19571,"test reporting api",web,192.168.1.1,NA,1473861348,1473861376,1,0,3
```

{% hint style="info" %}
**NOTE**: A successful response will always contain the header fields of the CSV. If you are paginating, be sure to trim this off before appending the rows to an existing CSV.
{% endhint %}

An unsuccessful request, one in which no csv rows were returned and the http code was not 200, contains the following item(s):

| Name  | Data Type | Always Present | Description                                           |
| ----- | --------- | -------------- | ----------------------------------------------------- |
| error | string    | yes            | Descriptive message indicating what error(s) occurred |

### **Sample Code**

This sample PHP code makes a request to fetch the first 10 items of a saved report:

```php
<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, "https://insight.plumvoice.com/api/report/1551?limit=10");
curl_setopt($ch, CURLOPT_USERPWD, 'your_login:your_dev_pin'); // http basic auth credentials
curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
curl_setopt($ch, CURLOPT_HTTPHEADER, array('Content-Type: application/x-www-form-urlencoded', 'Accept: application/json'));
curl_setopt($ch, CURLOPT_HEADER, 1); // return headers
$result = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE);
$headers = substr($result, 0, curl_getinfo($ch, CURLINFO_HEADER_SIZE)); // get just the headers
$body = substr($result, curl_getinfo($ch, CURLINFO_HEADER_SIZE)); // get everything after the headers
if ($http_code == 200) {
	// $body will contain the actual csv data
	// you can write this directly to a file
	file_put_contents('reports/todays_report.csv', $body);
	// or output it
	echo $headers."\n";
	echo $body."\n";
	// or whatever you would like..
} else {
	// non 200 indicates we did not get csv data, print the json body
	echo $body;
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.plumvoice.com/insight/api/survey-response-reporting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.