{% extends "_templates/base.html" %}
{% set page_title = "Statistics and Status Updates" %}
{% block sidebar %}
{{ api_links(methods=['getUploads'], events=['statusChange']) }}
{% endblock %}
{% block content %}
{% markdown %}

# Statistics and Status Updates {: .page-header }

Fine Uploader provides API methods and other options to facilitate statistics
and status updates on your uploads.

With this, we can register a callback that allows us to be notified
when any submitted item changes status.  The concept is simple: this will be
invoked whenever any submitted file changes state. The ID, old status, and the
new status will be included in the callback parameters.

The status values correspond to those found in the `qq.status` object.
For reference, here are valid status values:

* `SUBMITTING` - Selected file is in the process of being submitted to the uploader.  Validation checks occur during this phase.
* `SUBMITTED` - Selected file has been successfully submitted to the uploader.  In UI mode, it is also now represented in the DOM.
* `QUEUED` - Uploads are in progress, but this one has not yet started due to lack of available connections.   It is waiting in line for an available connection before an attempt is made to upload it.
* `UPLOADING` - File is currently uploading (in progress).
* `UPLOAD_RETRYING` - The state when an upload retry is about to occur, just before the upload retry it attempted.  The file will likely only be in this state for a brief moment.
* `UPLOAD_FAILED` - The upload has officially failed to upload, after all auto-retry attempts have been exhausted.
* `UPLOAD_SUCCESSFUL` - The upload has officially succeeded.
* `CANCELED` - The upload has been canceled.
* `REJECTED` - The submitted file has failed validation, either via the internal validation checks, or via a `validate`, `validateBatch`, or `submit` event callback.
* `DELETED` - The file has been successfully deleted from the server.
* `DELETING` - A delete attempt is in progress.
* `DELETE_FAILED` - The last delete attempt failed.
* `PAUSED` - The file was in progress, but is now paused.

----

### Examples

#### Simple status query

The API method allows you the retrieve information about all items submitted to
the uploader. If you invoke this method without any arguments, information on
all items will be returned.  For example, suppose we have submitted only two
files to the uploader, and both have uploaded successfully. If we wanted to retrieve
information about these files, the following code should be executed.  Note that I
have illustrated the expected return value as well:

```javascript
var uploads = myUploader.getUploads();

//the uploads return value will look like this:
[
  {
    id: 0,
    name: "some_name",
    size: 12345,
    uuid: "some_uuid",
    status: "upload successful"
  },
  {
    id: 1,
    name: "some_other_name",
    size: 67890,
    uuid: "some_other_uuid",
    status: "upload successful"
  }
]

```

Now, suppose we delete the second files via Fine Uploader. If we invoke a new-argument getUploads() again,
we receive the following in return:

```javascript
var uploads = myUploader.getUploads();

//the uploads return value will look like this:
[
  {
    id: 0,
    name: "some_name",
    size: 12345,
    uuid: "some_uuid",
    status: "upload successful"
  },
  {
    id: 1,
    name: "some_other_name",
    size: 67890,
    uuid: "some_other_uuid",
    status: "deleted"
  }
]
```


#### Filtering results

Note that you can filter by ID(s) OR UUID(s) OR status.  You can include multiple
ID, UUID, or status values as an array as well. All valid status values
are defined in the `qq.status` object. Also, please note that the `size` property
will only be included if the user agent supports the File API (that is, if
qq.supportedFeatures.canDetermineSize evaluates to true).

Suppose we only want to compile a list of all deleted files for this instance, we can do this:

```javascript
var uploads = myUploader.getUploads({
  status: qq.status.DELETED
});

//the uploads return value will look like this:
[
  {
    id: 1,
    name: "some_other_name",
    size: 67890,
    uuid: "some_other_uuid",
    status: "deleted"
  }
]
```

Now, suppose we have submitted another file, but we have canceled it.  Maybe we only want
information about canceled OR deleted items:

```javascript
var uploads = myUploader.getUploads({
  status: [qq.status.DELETED, qq.status.CANCELED]
});

//the uploads return value will look like this:
[
  {
    id: 1,
    name: "some_other_name",
    size: 67890,
    uuid: "some_other_uuid",
    status: "deleted"
  },
    {
    id: 2,
    name: "some_other_name_2",
    size: 11111,
    uuid: "some_other_uuid2",
    status: "canceled"
  }
]
```

{{ alert("getUploads returns an array only when there is a potential for the operation to return more than
one file in the result set. This excludes queries for a specific, single ID or UUID. All other queries will
return an array.", "info", "Note:") }}


#### Determine if all submitted files are "done"

How can I determine if all of my uploads are complete?  This is very much a frequently asked question.
Luckily, is quite simple to make this determination by contributing [an `onAllComplete` event handler][allcomplete].

[allcomplete]: ../api/events.html#allComplete

{% endmarkdown %}
{% endblock %}