When marker is supplied, does a request to list objects start with that key, or one after the key?

Question

The documentation for AWS for Ruby has for AWS::S3::Client#list_objects has

:marker (String) — Specifies the key to start with when listing objects in a bucket.

which I assume would mean that if you passed in marker: 'foo/bar.baz', then the object with a key of 'foo/bar.baz' would be included in the results.

However, the language-neutral documentation for listing objects GET Bucket (List Objects) says (emphasis added)

marker

Specifies the key to start with when listing objects in a bucket. Amazon S3 returns object keys in alphabetical order, starting with key after the marker in order.

Type: String

Default: None

Experimentation with actual Ruby code suggests the latter is correct, but what is the specified behaviour? Including, or excluding, the object with a key matching the value of marker?

Answer 1

Note that both the ruby and the API documentation begin with the same phrase:

Specifies the key to start with when listing objects in a bucket.

However, this is where S3 starts its search, not it's listing.

Results actually begin with the next object key after the marker.

(This is also true If the key designated by the marker doesn't actually exist -- results begin with the next key).