# Account Reports {% hint style="warning" %} **Welcome to Our New API Docs!** This is the new home for all things API (previously at [Canvas LMS REST API Documentation](https://api.instructure.com)). {% endhint %} ## Account Reports API API for accessing account reports. **A Report object looks like:** ```js { // The unique identifier for the report. "id": 1, // The type of report. "report": "sis_export_csv", // The url to the report download. "file_url": "https://example.com/some/path", // The attachment api object of the report. Only available after the report has // completed. "attachment": null, // The status of the report "status": "complete", // The date and time the report was created. "created_at": "2013-12-01T23:59:00-06:00", // The date and time the report started processing. "started_at": "2013-12-02T00:03:21-06:00", // The date and time the report finished processing. "ended_at": "2013-12-02T00:03:21-06:00", // The time (in seconds) the report has been waiting to run, has been running so // far, or took to run to completion, depending on its current state. "run_time": 33.3, // The report parameters "parameters": {"course_id":2,"start_at":"2012-07-13T10:55:20-06:00","end_at":"2012-07-13T10:55:20-06:00"}, // The progress of the report "progress": 100, // This is the current line count being written to the report. It updates every // 1000 records. "current_line": 12000, // The user that initiated the account report. See the Users API for details. "user": null } ``` **A ReportParameters object looks like:** ```js // The parameters returned will vary for each report. { // The canvas id of the term to get grades from "enrollment_term_id": 2, // If true, deleted objects will be included. If false, deleted objects will be // omitted. "include_deleted": false, // The id of the course to report on "course_id": 2, // The sort order for the csv, Options: 'users', 'courses', 'outcomes'. "order": "users", // If true, user data will be included. If false, user data will be omitted. "users": false, // If true, account data will be included. If false, account data will be // omitted. "accounts": false, // If true, term data will be included. If false, term data will be omitted. "terms": false, // If true, course data will be included. If false, course data will be omitted. "courses": false, // If true, section data will be included. If false, section data will be // omitted. "sections": false, // If true, enrollment data will be included. If false, enrollment data will be // omitted. "enrollments": false, // If true, group data will be included. If false, group data will be omitted. "groups": false, // If true, data for crosslisted courses will be included. If false, data for // crosslisted courses will be omitted. "xlist": false, "sis_terms_csv": 1, "sis_accounts_csv": 1, // If true, enrollment state will be included. If false, enrollment state will // be omitted. Defaults to false. "include_enrollment_state": false, // Include enrollment state. Defaults to 'all' Options: ['active'| 'invited'| // 'creation_pending'| 'deleted'| 'rejected'| 'completed'| 'inactive'| 'all'] "enrollment_state": ["all"], // The beginning date for submissions. Max time range is 2 weeks. "start_at": "2012-07-13T10:55:20-06:00", // The end date for submissions. Max time range is 2 weeks. "end_at": "2012-07-13T10:55:20-06:00" } ``` ### [List Available Reports](#method.account_reports.available_reports) [AccountReportsController#available\_reports](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) **`GET /api/v1/accounts/:account_id/reports`** **Scope:** `url:GET|/api/v1/accounts/:account_id/reports` Returns a paginated list of reports for the current context. **Request Parameters:** | Parameter | Type | Description | | ----------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `include[]` | `string` |

Array of additional information to include.


Allowed values: description\_html, params\_html

| **API response field:** * name The name of the report. * parameters The parameters will vary for each report * last\_run * Report The last run of the report. This will be null if the report has never been run. **Example Request:** ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports/ ``` **Example Response:** ```js [ { "report":"student_assignment_outcome_map_csv", "title":"Student Competency", "parameters":null, "last_run": { "id": 1, "report": "student_assignment_outcome_map_csv", "file_url": "https://example.com/some/path", "status": "complete", "created_at": "2013-12-01T23:59:00-06:00", "started_at": "2013-12-02T00:03:21-06:00", "ended_at": "2013-12-02T00:03:21-06:00" }, { "report":"grade_export_csv", "title":"Grade Export", "parameters":{ "term":{ "description":"The canvas id of the term to get grades from", "required":true } }, "last_run": null } ] ``` ### [Start a Report](#method.account_reports.create) [AccountReportsController#create](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) **`POST /api/v1/accounts/:account_id/reports/:report`** **Scope:** `url:POST|/api/v1/accounts/:account_id/reports/:report` Generates a report instance for the account. Note that “report” in the request must match one of the available report names. To fetch a list of available report names and parameters for each report (including whether or not those parameters are required), see [List Available Reports](#method.account_reports.available_reports). **Request Parameters:** | Parameter | Type | Description | | -------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `parameters[]` | `Hash` | The parameters will vary for each report. To fetch a list of available parameters for each report, see [List Available Reports](#method.account_reports.available_reports). A few example parameters have been provided below. Note that the example parameters provided below may not be valid for every report. | | `parameters[skip_message]` | `boolean` | If true, no message will be sent to the user upon completion of the report. | | `parameters[course_id]` | `integer` | The id of the course to report on. Note: this parameter has been listed to serve as an example and may not be valid for every report. | | `parameters[users]` | `boolean` | If true, user data will be included. If false, user data will be omitted. Note: this parameter has been listed to serve as an example and may not be valid for every report. | **Example Request:** ```bash curl -X POST \ https:///api/v1/accounts/1/reports/provisioning_csv \ -H 'Authorization: Bearer ' \ -H 'Content-Type: multipart/form-data' \ -F 'parameters[users]=true' \ -F 'parameters[courses]=true' \ -F 'parameters[enrollments]=true' ``` Returns a [Report](https://developerdocs.instructure.com/services/canvas/course_reports#report) object. ### [Index of Reports](#method.account_reports.index) [AccountReportsController#index](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) **`GET /api/v1/accounts/:account_id/reports/:report`** **Scope:** `url:GET|/api/v1/accounts/:account_id/reports/:report` Shows all reports that have been run for the account of a specific type. **Example Request:** ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports/ ``` Returns a list of [Report](https://developerdocs.instructure.com/services/canvas/course_reports#report) objects. ### [Status of a Report](#method.account_reports.show) [AccountReportsController#show](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) **`GET /api/v1/accounts/:account_id/reports/:report/:id`** **Scope:** `url:GET|/api/v1/accounts/:account_id/reports/:report/:id` Returns the status of a report. **Example Request:** ```bash curl -H 'Authorization: Bearer ' \ https:///api/v1/accounts//reports// ``` Returns a [Report](https://developerdocs.instructure.com/services/canvas/course_reports#report) object. ### [Delete a Report](#method.account_reports.destroy) [AccountReportsController#destroy](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) **`DELETE /api/v1/accounts/:account_id/reports/:report/:id`** **Scope:** `url:DELETE|/api/v1/accounts/:account_id/reports/:report/:id` Deletes a generated report instance. **Example Request:** ```bash curl -H 'Authorization: Bearer ' \ -X DELETE \ https:///api/v1/accounts//reports// ``` Returns a [Report](https://developerdocs.instructure.com/services/canvas/course_reports#report) object. ### [Abort a Report](#method.account_reports.abort) [AccountReportsController#abort](https://github.com/instructure/canvas-lms/blob/master/app/controllers/account_reports_controller.rb) **`PUT /api/v1/accounts/:account_id/reports/:report/:id/abort`** **Scope:** `url:PUT|/api/v1/accounts/:account_id/reports/:report/:id/abort` Abort a report in progress **Example Request:** ```bash curl -H 'Authorization: Bearer ' \ -X PUT \ https:///api/v1/accounts//reports///abort ``` Returns a [Report](https://developerdocs.instructure.com/services/canvas/course_reports#report) object. *** This documentation is generated directly from the Canvas LMS source code, available [on Github](https://github.com/instructure/canvas-lms). --- # Agent Instructions: 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: ``` GET https://developerdocs.instructure.com/services/canvas/resources/account_reports.md?ask= ``` The question should be specific, self-contained, and written in natural language. 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.