GET /{db}/_changes

In this document

This request retrieves a sorted list of changes made to documents in the database, in time order of application, can be obtained from the database’s _changes resource. Only the most recent change for a given document is guaranteed to be provided. For example if a document has had fields added, and then deleted, an API client checking for changes will not necessarily receive the intermediate state of added documents.

This request can be used to listen for update and modifications to the database for post processing or synchronization. A continuously connected changes feed is a reasonable approach for generating a real-time log for most applications.

Request

Request headers

This request does not have any required headers.

Query parameters

Name	Type	Description	Default
`attachments`	Boolean	Indicates whether to include the Base64-encoded content of attachments in the documents that are included when `include_docs` is true. this parameter is ignored when `include_docs` is false.	false
`att_encoding_info`	Boolean	Indicates whether to include encoding information in attachment stubs when `include_docs` is true.	false
`conflicts`	Boolean	Includes conflicts information in response. Ignored if include_docs isn’t true.	false
`descending`	Boolean	Return the change results in descending sequence order (most recent change first).	false
`doc_ids`	array	List of document IDs to filter the changes feed as valid JSON array. Used with _doc_ids filter.	none
`feed`	string	Specifies type of change feed. Valid values: `normal`, `continuous`, `eventsource`, `longpoll`	`normal`
`filter`	string	Reference to a filter function from a design document that will filter whole stream emitting only filtered events.	none
`heartbeat`	integer	Period in milliseconds after which an empty line is sent in the results. Only applicable for longpoll or continuous feeds. Overrides any timeout to keep the feed alive indefinitely.	60000
`include_docs`	Boolean	Indicates whether to include the associated document with each result. f there are conflicts, only the winning revision is returned.	false
`last-event-id`	integer	Alias for the `Last-Event-ID` header.	none
`limit`	integer	Limits the number of result rows to the specified value. Using a value of 0 has the same effect as the value 1.	none
`since`	integer	Starts the results from the change immediately after the given sequence number. The value can be an integer or a row value.	0
`style`	string	Number of revisions to return in the `changes` array. `main_only` returns the current winning revision, `all_docs` returns all leaf revisions including conflicts and deleted former conflicts.	`main_only`
`timeout`	integer	Maximum period in milliseconds to wait for a change before the response is sent, even if there are no results. Only applicable for `longpoll` or `continuous` feeds. The default value is specified by the httpd/changes_timeout configuration option. If not specified, the default maximum timeout is used to prevent undetected dead connections.	60000
`view`	string	Name of a view function to use as a filter	none

Response

Status codes

200 OK – Request completed successfully
400 Bad Request – Bad request

Response headers

This response uses only standard HTTP headers.

Message body

The response message body contains a JSON document with the following objects;

Name	Type	Description
`last_seq`	integer	Last change sequence number
`results`	array	List of changes to the database. See the following table for a list of fields in this object.

The results array contains the following objects:

Name	Type	Description
`changes`	array	List of the document’s leafs. Each leaf object contains one field, `rev`.
`id`	string	Document identifier
`seq`	integer	Update sequence number

Example

The following example requests the changes to the database named cookbook and specifies that only two rows be included in the response:

Request

GET /cookbook/_changes?limit=2 HTTP/1.1
Host: localhost:59840

Response

HTTP/1.1 200 OK
Accept-Ranges: bytes
Cache-Control: must-revalidate
Content-Type: application/json
Date: Mon, 16 Dec 2013 21:09:35 GMT
Etag: "13"
Server: CouchbaseLite 1.486
Transfer-Encoding: chunked
{
  "results" : [
    {
      "seq" : 1,
      "id" : "A329CFEC-29E8-4DCF-BB49-EFCE8CD6B212",
      "changes" : [
        {
          "rev" : "1-afbf905396a144446feb2431c37065f9"
        }
      ]
    },
    {
      "seq" : 2,
      "id" : "209BB170-C1E0-473E-B3C4-A4533ACA3CDD",
      "changes" : [
        {
          "rev" : "1-ed0ebedd2fab89227b352f6455a08010"
        }
      ]
    }
  ],
  "last_seq" : 2
}