Instructure Developer Documentation Portal
Community
  • Introduction
  • Services
    • Elevate Standards Alignment - AB Connect API
      • Introduction
        • Authentication
        • Addressing Object Properties
        • Requesting Additional Properties in the Response
        • Filtering Using ODATA Like Statements
        • Sorting
        • Facets
        • Paging Data
        • Call Throttling
        • Working with Related Object
        • Error Responses
        • Character Set Support
        • How To Articles, Recommendations and Suggestions
        • Examples
        • Using AB Connect's Embeddable Widgets
      • Reference
        • Standards
        • Standard Collections
        • Events
        • Topics
        • Concepts
        • Assets
        • Asset Definitions
        • Asset Collections
        • Managing and Predicting Relationships
        • Providers
    • Canvas LMS
      • Basics
        • GraphQL
        • API Change Log
        • SIS IDs
        • Pagination
        • Throttling
        • Compound Documents
        • File Uploads
        • API Endpoint Attributes
        • Masquerading
      • OAuth2
        • OAuth2 Overview
        • OAuth2 Endpoints
        • Developer Keys
      • Resources
        • Access Tokens
        • Account Calendars
        • Account Domain Lookups
        • Account Notifications
        • Account Reports
        • Accounts
        • Accounts (LTI)
        • Admins
        • Analytics
        • Announcement External Feeds
        • Announcements
        • API Token Scopes
        • Appointment Groups
        • Assignment Extensions
        • Assignment Groups
        • Assignments
        • Authentication Providers
        • Authentications Log
        • Blackout Dates
        • BlockEditorTemplate
        • Blueprint Courses
        • Bookmarks
        • Brand Configs
        • Calendar Events
        • Collaborations
        • CommMessages
        • Communication Channels
        • Conferences
        • Content Exports
        • Content Migrations
        • Content Security Policy Settings
        • Content Shares
        • Conversations
        • Course Audit log
        • Course Pace
        • Course Quiz Extensions
        • Course Reports
        • Courses
        • Custom Gradebook Columns
        • Developer Key Account Bindings
        • Developer Keys
        • Discussion Topics
        • Enrollment Terms
        • Enrollments
        • ePortfolios
        • ePub Exports
        • Error Reports
        • External Tools
        • Favorites
        • Feature Flags
        • Files
        • Grade Change Log
        • Gradebook History
        • Grading Period Sets
        • Grading Periods
        • Grading Standards
        • Group Categories
        • Groups
        • History
        • InstAccess tokens
        • JWTs
        • Late Policy
        • Learning Object Dates
        • Line Items
        • LiveAssessments
        • Logins
        • LTI Launch Definitions
        • LTI Registrations
        • LTI Resource Links
        • Media Objects
        • Moderated Grading
        • Modules
        • Names and Role
        • New Quiz Items
        • New Quizzes
        • New Quizzes Accommodations
        • New Quizzes Reports
        • Notification Preferences
        • Originality Reports
        • Outcome Groups
        • Outcome Imports
        • Outcome Results
        • Outcomes
        • Pages
        • Peer Reviews
        • Planner
        • Poll Sessions
        • PollChoices
        • Polls
        • PollSubmissions
        • Proficiency Ratings
        • Progress
        • Public JWK
        • Quiz Assignment Overrides
        • Quiz Extensions
        • Quiz IP Filters
        • Quiz Question Groups
        • Quiz Questions
        • Quiz Reports
        • Quiz Statistics
        • Quiz Submission Events
        • Quiz Submission Files
        • Quiz Submission Questions
        • Quiz Submission User List
        • Quiz Submissions
        • Quizzes
        • Result
        • Roles
        • Rubrics
        • Sandboxes
        • Score
        • Search
        • Sections
        • Services
        • Shared Brand Configs
        • SIS Import Errors
        • SIS Imports
        • SIS Integration
        • Smart Search
        • Submission Comments
        • Submissions
        • Tabs
        • Temporary Enrollment Pairings
        • User Observees
        • Users
        • What If Grades
      • Outcomes
        • Outcomes CSV Format
      • Group Categories
        • Group Categories CSV Format
      • SIS
        • SIS CSV Format
      • External Tools
        • LTI
          • Introduction
          • Registration
          • Launch Overview
          • Configuring
          • Variable Substitutions
          • Deep Linking
          • Grading
          • Provisioning
          • PostMessage
          • Platform Notification Service
          • Placements
            • Placements Overview
            • Navigation
            • Homework Submission
            • Editor Button
            • Migration Selection
            • Link Selection (Modules)
            • Assignment Selection
            • Collaborations
        • xAPI
        • Canvas Roles
        • Plagiarism Detection Platform
          • Overview
          • Plagiarism Detection Platform Assignments
          • Plagiarism Detection Platform Users
          • Plagiarism Detection Submissions
          • Webhooks Subscriptions for Plagiarism Platform
          • JWT Access Tokens
      • Data Services
        • Live Events
          • Overview
            • Introduction
            • Setup
            • Caliper
            • Metadata
          • Event Format
            • Canvas
              • Account
              • Asset
              • Assignment
              • Attachment
              • Content
              • Conversation
              • Course
              • Discussion
              • Enrollment
              • Grade
              • Group
              • Learning
              • Logged
              • Module
              • Outcome
              • Outcomes
              • Plagiarism
              • Quiz
              • Rubric
              • Sis
              • Submission
              • Syllabus
              • User
              • Wiki
            • Caliper IMS 1.1
              • Assessment
              • Basic
              • Forum
              • Grading
              • Navigation Events
              • Session
    • Catalog
      • APIs
        • Analytics
        • Bulk Enrollments
        • Catalogs
        • Certificates
        • Completed Certificates
        • Courses
        • Email Domain Set
        • Enrollments
        • Orders
        • Programs
        • Progresses
        • Tags
        • User Registrations
        • Users
        • Waitlist Applicants
    • Credentials
      • Getting Started
      • Authentication
        • Password-Based Authentication
        • Authorization Code-Based Authentication
      • Pagination
      • APIs
        • Assertions
        • Backpack
        • Badgeclasses
        • Issuers
        • Organizations
        • Users
      • Release Notes
    • Data Access Platform
      • Key Concepts
      • Data Formats
      • Rate Limits & Policies
      • Datasets
        • Namespaces
          • canvas
            • canvas types
          • canvas_logs
          • catalog
        • Additional Notes
        • Entity Relationship Diagram
      • Query API
        • Authentication
        • Reference
      • Command Line (DAP CLI)
        • Getting Started
        • Secure Connection
        • Reference
          • dap snapshot
          • dap incremental
          • dap list
          • dap schema
          • dap initdb
          • dap syncdb
          • dap dropdb
      • Client Library
        • Examples
        • Reference
      • Release Notes
      • Status
    • DataSync
      • Interop API
      • Interop Data API
      • Grades Exchange API
      • OneRoster API
      • Platform API
    • Instructure Media
      • API Reference
        • Captions
        • Collection
        • Courses
        • Group
        • Insights
        • Media
        • Media Upload
        • Ping
        • Professional Captioning
        • Tags
        • Transfer Media
        • User
    • Quizzes
      • Quiz API
Powered by GitBook

Copyright © 2008-2024 Instructure, Inc. All rights reserved. Various trademarks held by their respective owners.

On this page

Was this helpful?

  1. Services
  2. Data Access Platform
  3. Query API

Reference

PreviousAuthenticationNextCommand Line (DAP CLI)

Last updated 6 months ago

Was this helpful?

List tables

get

If no scope is specified, then the endpoint uses the default scope of the authenticated user. Returns an error if the user has access to several scopes and the scope is not explicitly specified.

Authorizations
Path parameters
namespacestringRequired

Identifies the domain or product that the request pertains to, e.g. canvas.

Query parameters
scopestringOptional

Identifies the scope to access, e.g. a root account UUID for Canvas, or a district ID for Mastery.

Responses
200
A list of tables in the given scope.
application/json
401
Client lacks valid authentication credentials.
application/json
404
The namespace does not exist.
application/json
500
The requested account has not been onboarded yet. **OR** The requested account has been onboarded but client access has been restricted. **OR** Internal server error.
application/json
504
Gateway timeout error, usually should be handled with retry logic.
application/json
get
GET /dap/query/{namespace}/table HTTP/1.1
Host: api-gateway.instructure.com
Authorization: Bearer JWT
Accept: */*
{
  "tables": [
    "accounts",
    "submissions",
    "users"
  ]
}

Get table schema

get

If data is returned in JSON Lines format (*.jsonl) then the schema applies to the JSON object obtained by combining the sub-objects accessed via the key and value properties, respectively, of JSON items.

Assume the schema reads as follows:

{
    "type": "object",
    "properties": {
        "pkey": {
            "type": "integer",
            "format": "int64"
        },
        "prop1": {
            "type": "string"
        },
        "prop2": {
            "type": "integer"
        },
        "additionalProperties": false,
        "required": [
            "pkey",
            "prop1"
        ]
    }
}

Suppose we have the following JSON output:

{ "meta": { "action": "U", ... }, "key": { "pkey": 1 }, "value": { "prop1": "value1", "prop2": 42 } }
{ "meta": { "action": "U", ... }, "key": { "pkey": 2 }, "value": { "prop1": "value2", "prop2": null } }
{ "meta": { "action": "D", ... }, "key": { "pkey": 3 } }

In the example directly above, the first and second items (update records) would both validate against the pre-defined schema. The validator would check the following synthesized JSON objects:

{ "pkey": 1, "prop1": "value1", "prop2": 42 }
{ "pkey": 2, "prop1": "value2", "prop2": null }

The third item (a delete record) does not have to validate because it indicates that the client is to remove the item.

If data is returned in Comma-Separated Values format (*.csv) then the schema type constraints apply to CSV key and value columns, respectively, but not CSV meta columns. For example, assume we have the following CSV output:

meta.action,key.pkey,value.prop1,value.prop2
U,1,"value1",42
U,2,"value2",
D,3,,

Then the schema would read the same as in the JSON example above.

Nested JSON objects are flattened to simple fields, with composite names constructed using the dot notation (parent.child).

If no scope is specified, then the endpoint uses the default scope of the authenticated user. Returns an error if the user has access to several scopes and the scope is not explicitly specified.

Authorizations
Path parameters
namespacestringRequired

Identifies the domain or product that the request pertains to, e.g. canvas.

tablestringRequired

Canonical name of the table whose schema to return.

Query parameters
scopestringOptional

Identifies the scope to access, e.g. a root account UUID for Canvas, or a district ID for Mastery.

Responses
200
The versioned JSON schema specification for the table.
application/json
401
Client lacks valid authentication credentials.
application/json
404
The namespace or table does not exist.
application/json
500
The requested account has not been onboarded yet. **OR** The requested account has been onboarded but client access has been restricted. **OR** Internal server error.
application/json
504
Gateway timeout error, usually should be handled with retry logic.
application/json
get
GET /dap/query/{namespace}/table/{table}/schema HTTP/1.1
Host: api-gateway.instructure.com
Authorization: Bearer JWT
Accept: */*
{
  "schema": {
    "type": "object",
    "properties": {
      "id": {
        "type": "integer",
        "format": "int64",
        "title": "The ID of this version object. Primary key."
      },
      "user_id": {
        "type": "integer",
        "format": "int64",
        "title": "The ID of the submitter. Foreign key to `users.id`."
      },
      "context_id": {
        "type": "integer",
        "format": "int64",
        "title": "The ID of the course this submission belongs to. Foreign key to `courses.id`."
      },
      "context_type": {
        "type": "string",
        "enum": [
          "Course"
        ],
        "title": "The type of the context object (typically `Course`)."
      }
    },
    "additionalProperties": false,
    "required": [
      "id",
      "context_type"
    ],
    "title": "This table stores information describing previous versions of individual submission objects."
  },
  "version": 1
}
  • GETGet job
  • POSTCreate pre-signed URLs
  • POSTCreate job
  • GETList tables
  • GETGet table schema

Get job

get

Jobs (and all objects they created) are deleted 24 hours after the job was started. Deleted jobs are no longer returned by this endpoint.

Authorizations
Path parameters
idstringRequired

Unique identifier returned when the job was started by querying data.

Responses
200
A snapshot query that has completed with success. **OR** An incremental query that has completed with success. **OR** A data access job that has terminated with failure.
application/json
Responseone of
or
or
202
A data access job in progress.
application/json
401
Client lacks valid authentication credentials.
application/json
404
The job does not exist or has expired.
application/json
500
The requested account has not been onboarded yet. **OR** The requested account has been onboarded but client access has been restricted. **OR** Internal server error.
application/json
504
Gateway timeout error, usually should be handled with retry logic.
application/json
get
GET /dap/job/{id} HTTP/1.1
Host: api-gateway.instructure.com
Authorization: Bearer JWT
Accept: */*
{
  "id": "text",
  "status": "waiting",
  "expires_at": "2025-05-25T20:28:59.484Z",
  "objects": [
    {
      "id": "text"
    }
  ],
  "schema_version": 1,
  "at": "2025-05-25T20:28:59.484Z"
}

Create pre-signed URLs

post

In contrast to objects, which have a longer lifetime, pre-signed URLs are valid for a shorter duration, typically 15 minutes.

File paths returned by this endpoint do not adhere to any specification. While they may contain auxiliary information such as job ID or part counter, these are only informative. Downstream systems should not depend on any specific patterns of file names, or make any assumptions how much data each file contains.

Authorizations
Body

The lifetime of the object depends on the operation that created it but typically lasts for 24 hours. Object identifiers can be traded for pre-signed URLs via an authenticated endpoint operation while the object exists.

idstringRequired

Uniquely identifies the object.

Responses
200
A list of pre-signed URLs.
application/json
400
The input is malformed.
application/json
401
Client lacks valid authentication credentials.
application/json
404
Objects do not exist or have expired.
application/json
500
The requested account has not been onboarded yet. **OR** The requested account has been onboarded but client access has been restricted. **OR** Internal server error.
application/json
504
Gateway timeout error, usually should be handled with retry logic.
application/json
post
POST /dap/object/url HTTP/1.1
Host: api-gateway.instructure.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 33

[
  {
    "id": "uuid-1"
  },
  {
    "id": "uuid-2"
  }
]
{
  "urls": {
    "ANY_ADDITIONAL_PROPERTY": {
      "url": "https://example.com"
    }
  }
}

Create job

post

This is an asynchronous operation. Calling this endpoint will start a new job and return immediately with status information. However, the operation will continue running on the server. The caller can poll the status of the job to find out when it is ready.

If a job with the same query parameters already exists, its details are returned rather than starting a new job.

If no scope is specified, then the endpoint uses the default scope of the authenticated user. Returns an error if the user has access to several scopes and the scope is not explicitly specified.

For incremental queries, the output uses a special metadata field called action to identify whether a record is upserted (inserted or updated) or (hard) deleted (U corresponds to upsert, and D to delete):

{ "meta": { "action": "U", ... }, "key": { "pkey": 1 }, "value": { "prop1": "value1", "prop2": 42 } }
{ "meta": { "action": "U", ... }, "key": { "pkey": 2 }, "value": { "prop1": "value2", "prop2": null } }
{ "meta": { "action": "D", ... }, "key": { "pkey": 3 } }

Upserted records have the primary key fields present in the sub-object key and all other data fields in the sub-object value. Deleted records only have the primary key fields in the key property, and lack the value property.

Hard deletes are infrequent. They only take place when a record is irreversibly deleted from the source database, e.g. to comply with privacy or legal requirements.

In most cases, records are soft-deleted, i.e. they are updated in such a way as to be understood deleted or inactive though the record is retained in the database, e.g. by setting a workflow_state column to the value inactive or deleted. In this context, soft deletes are equivalent to an update, and are denoted with a U, and all field values are included in the output.

In the rare event that inserting a record is quickly followed by a hard delete in the source database between two successive incremental queries, a record might appear with a new (so far unseen) key, no value and an action of D.

For snapshot queries, deleted records are not included in the output:

{ "meta": { ... }, "key": { "pkey": 1 }, "value": { "prop1": "value1", "prop2": 42 } }
{ "meta": { ... }, "key": { "pkey": 2 }, "value": { "prop1": "value2", "prop2": null } }

This is a rate-limited endpoint. If excessive data volume is requested repeatedly using this endpoint (e.g. a full snapshot every hour), future requests may be denied. We encourage making use of incremental queries, which substantially reduce the amount of data returned.

Difference between snapshot and incremental Queries:

Snapshot queries and incremental queries serve different purposes in data retrieval and management within the DAP environment.

  • Snapshot Queries: These queries generate a complete and comprehensive snapshot of the entire dataset at a given point in time. However, note that for the canvas_logs dataset, particularly the web_logs table, there is a 30-day data retention policy, so the snapshot will not cover the entire dataset but only the last 30 days of data. Snapshot queries are ideal for creating an initial full copy of the dataset or for occasional full updates. It is not recommended to request snapshots regularly, as it is resource-intensive on the API side and expensive to process on the client side. This approach ensures that you have a full, standalone version of the data, which can be useful for comprehensive analyses, audits, and backups.
  • Incremental Queries: In contrast, incremental queries retrieve only the changes or updates that have occurred since the last query. This method is more efficient and resource-effective as it minimizes data transfer by only fetching new or modified records. Incremental queries are ideal for keeping your dataset up-to-date with minimal overhead, enabling near-real-time data updates and reducing the need for frequent full dataset downloads.

It is recommended taking a snapshot exactly once (as an initialization step) and then using incremental queries thereafter. By utilizing snapshot queries for initial data load and incremental queries for subsequent updates, users can maintain up-to-date datasets efficiently and effectively.

Authorizations
Path parameters
namespacestringRequired

Identifies the domain or product that the request pertains to, e.g. canvas.

tablestringRequired

Canonical name of the table whose data to return.

Query parameters
scopestringOptional

Identifies the scope to access, e.g. a root account UUID for Canvas, or a district ID for Mastery.

Body
one ofOptional
or
Responses
200
A snapshot query that has completed with success. **OR** An incremental query that has completed with success. **OR** A data access job that has terminated with failure.
application/json
Responseone of
or
or
202
A data access job in progress.
application/json
400
The input is malformed. **OR** There is no data in the requested range. **OR** Raised when data is queried outside of the allowed time range, and the table was reloaded recently.
application/json
401
Client lacks valid authentication credentials.
application/json
404
The namespace or table does not exist.
application/json
500
The requested account has not been onboarded yet. **OR** The requested account has been onboarded but client access has been restricted. **OR** Internal server error.
application/json
504
Gateway timeout error, usually should be handled with retry logic.
application/json
post
POST /dap/query/{namespace}/table/{table}/data HTTP/1.1
Host: api-gateway.instructure.com
Authorization: Bearer JWT
Content-Type: application/json
Accept: */*
Content-Length: 80

{
  "format": "jsonl",
  "since": "2022-07-14T10:30:00Z",
  "until": "2022-07-14T14:30:00Z"
}
{
  "id": "text",
  "status": "waiting",
  "expires_at": "2025-05-25T20:28:59.484Z",
  "objects": [
    {
      "id": "text"
    }
  ],
  "schema_version": 1,
  "at": "2025-05-25T20:28:59.484Z"
}