API Reference 

Shotgun.get_session_token() → str[source]

Get the session token associated with the current session.

If a session token has already been established, this is returned, otherwise a new one is generated on the server and returned.

>>> sg.get_session_token()
dd638be7d07c39fa73d935a775558a50

Returns:: String containing a session token.
Return type:: str

Shotgun.get_auth_cookie_handler() → HTTPCookieProcessor[source]

Return an urllib cookie handler containing a cookie for FPTR authentication.

Looks up session token and sets that in a cookie in the urllib2 handler. This is used internally for downloading attachments from FPTR.

Shotgun.add_user_agent(agent: str) → None[source]

Add agent to the user-agent header.

Appends agent to the user-agent string sent with every API request.

>>> sg.add_user_agent("my_tool 1.0")

Parameters:: agent (str) – string to append to user-agent.

Shotgun.reset_user_agent() → None[source]

Reset user agent to the default value.

Example default user-agent:

shotgun-json (3.0.17); Python 2.6 (Mac); ssl OpenSSL 1.0.2d 9 Jul 2015 (validate)

Shotgun.set_session_uuid(session_uuid: str) → None[source]

Set the browser session_uuid in the current Shotgun API instance.

When this is set, any events generated by the API will include the session_uuid value on the corresponding EventLogEntries. If there is a current browser session open with this session_uuid, the browser will display updates for these events.

>>> sg.set_session_uuid("5a1d49b0-0c69-11e0-a24c-003048d17544")

Parameters:: session_uuid (str) – The uuid of the browser session to be updated.

Shotgun.info() → Dict[str, Any][source]

Get API-related metadata from the Shotgun server.

>>> sg.info()
{'full_version': [8, 2, 1, 0], 'version': [8, 2, 1], 'user_authentication_method': 'default', ...}

Token                       Value
--------                    ---------
full_version                An ordered array of the full Shotgun version.
                            [major, minor, patch, hotfix]
version                     An ordered array of the Shotgun version.
                            [major, minor, patch]
user_authentication_method  Indicates the authentication method used by Shotgun.
                            Will be one of the following values:
                                default: regular username/password.
                                ldap:    username/password from the company's LDAP.
                                saml2:   SSO used, over SAML2.

Note

Beyond the documented tokens, you should expect the other values to be unsupported and for internal use only.

Returns:: dict of the server metadata.
Return type:: dict

Subscription Management

These methods are used for reading and assigning user subscriptions.

Shotgun.user_subscriptions_read() → List[source]

Get the list of user subscriptions.

Returns:: A list of user subscriptions where each subscription is a dictionary containing the humanUserId and subscription fields.
Return type:: list

Shotgun.user_subscriptions_create(users: List[Dict[str, str | List[str] | None]]) → bool[source]

Assign subscriptions to users.

Parameters:: users (list) – list of user subscriptions to assign. Each subscription must be a dictionary with the humanUserId and subscription fields. The subscription is either None, a single string, or an array of strings with subscription information.
Returns:: True if the request succedeed, False if otherwise.
Return type:: bool

CRUD Methods

These are the main methods for creating, reading, updating, and deleting information. There are also some specialized convenience methods for accessing particular types of information.

Shotgun.create(entity_type: str, data: Dict[str, Any], return_fields: List[str] | None = None) → Dict[str, Any][source]

Create a new entity of the specified entity_type.

>>> data = {
...     "project": {"type": "Project", "id": 161},
...     "sg_sequence": {"type": "Sequence", "id": 109},
...     "code": "001_100",
...     'sg_status_list': "ip"
... }
>>> sg.create('Shot', data)
{'code': '001_100',
 'id': 2557,
 'project': {'id': 161, 'name': 'Pied Piper', 'type': 'Project'},
 'sg_sequence': {'id': 109, 'name': 'Sequence 001', 'type': 'Sequence'},
 'sg_status_list': 'ip',
 'type': 'Shot'}

Parameters:

entity_type (str) – Shotgun entity type to create.
data (dict) – Dictionary of fields and corresponding values to set on the new entity. If image or filmstrip_image fields are provided, the file path will be uploaded to the server automatically.
return_fields (list) –
Optional list of additional field values to return from the new entity. Defaults to id field.

See also

Combining Related Queries

Returns:

Shotgun entity dictionary containing the field/value pairs of all of the fields set from the data parameter as well as the defaults type and id. If any additional fields were provided using the return_fields parameter, these would be included as well.

See also

Entity Fields

Return type:

Shotgun.find(entity_type: str, filters: List | Tuple | Dict[str, Any], fields: List[str] | None = None, order: List[OrderItem] | None = None, filter_operator: str | None = None, limit: int = 0, retired_only: bool = False, page: int = 0, include_archived_projects: bool = True, additional_filter_presets: List[Dict[str, Any]] | None = None) → List[BaseEntity][source]

Find entities matching the given filters.

>>> # Find Character Assets in Sequence 100_FOO
>>> # -------------
>>> fields = ['id', 'code', 'sg_asset_type']
>>> sequence_id = 2 # Sequence "100_FOO"
>>> project_id = 4 # Demo Project
>>> filters = [
...     ['project', 'is', {'type': 'Project', 'id': project_id}],
...     ['sg_asset_type', 'is', 'Character'],
...     ['sequences', 'is', {'type': 'Sequence', 'id': sequence_id}]
... ]
>>> assets= sg.find("Asset",filters,fields)
[{'code': 'Gopher', 'id': 32, 'sg_asset_type': 'Character', 'type': 'Asset'},
 {'code': 'Cow', 'id': 33, 'sg_asset_type': 'Character', 'type': 'Asset'},
 {'code': 'Bird_1', 'id': 35, 'sg_asset_type': 'Character', 'type': 'Asset'},
 {'code': 'Bird_2', 'id': 36, 'sg_asset_type': 'Character', 'type': 'Asset'},
 {'code': 'Bird_3', 'id': 37, 'sg_asset_type': 'Character', 'type': 'Asset'},
 {'code': 'Raccoon', 'id': 45, 'sg_asset_type': 'Character', 'type': 'Asset'},
 {'code': 'Wet Gopher', 'id': 149, 'sg_asset_type': 'Character', 'type': 'Asset'}]

You can drill through single entity links to filter on fields or display linked fields. This is often called “deep linking” or using “dot notation”.

See also

Filter Syntax

>>> # Find Versions created by Tasks in the Animation Pipeline Step
>>> # -------------
>>> fields = ['id', 'code']
>>> pipeline_step_id = 2 # Animation Step ID
>>> project_id = 4 # Demo Project
>>> # you can drill through single-entity link fields
>>> filters = [
...     ['project','is', {'type': 'Project','id': project_id}],
...     ['sg_task.Task.step.Step.id', 'is', pipeline_step_id]
>>> ]
>>> sg.find("Version", filters, fields)
[{'code': 'scene_010_anim_v001', 'id': 42, 'type': 'Version'},
 {'code': 'scene_010_anim_v002', 'id': 134, 'type': 'Version'},
 {'code': 'bird_v001', 'id': 137, 'type': 'Version'},
 {'code': 'birdAltBlue_v002', 'id': 236, 'type': 'Version'}]

Parameters:

entity_type (str) – Shotgun entity type to find.
filters (list) –
list of filters to apply to the query.

See also

Filter Syntax, Combining Related Queries
fields (list) –
Optional list of fields to include in each entity record returned. Defaults to ["id"].

See also

Combining Related Queries
order (list) –
Optional list of dictionaries defining how to order the results of the query. Each dictionary contains the field_name to order by and the direction to sort:
```
[
    {'field_name':'foo', 'direction':'asc'},
    {'field_name':'bar', 'direction':'desc'}
]
```
Defaults to sorting by id in ascending order.
filter_operator (str) – Operator to apply to the filters. Supported values are "all" and "any". These are just another way of defining if the query is an AND or OR query. Defaults to "all".
limit (int) – Optional limit to the number of entities to return. Defaults to 0 which returns all entities that match.
page (int) – Optional page of results to return. Use this together with the limit parameter to control how your query results are paged. Defaults to 0 which returns all entities that match.
retired_only (bool) – Optional boolean when True will return only entities that have been retired. Defaults to False which returns only entities which have not been retired. There is no option to return both retired and non-retired entities in the same query.
include_archived_projects (bool) – Optional boolean flag to include entities whose projects have been archived. Defaults to True.
additional_filter_presets (list) –
Optional list of presets to further filter the result set, list has the form:
```
[{
    "preset_name": <preset_name>,
    <optional_param1>: <optional_value1>,
    ...
}]
```
Note that these filters are ANDed together and ANDed with the ‘filter’ argument.

For details on supported presets and the format of this parameter see Additional Filter Presets

Returns:

list of dictionaries representing each entity with the requested fields, and the defaults "id" and "type" which are always included.

See also

Entity Fields

Return type:

Shotgun.find_one(entity_type: str, filters: List | Tuple | Dict[str, Any], fields: List[str] | None = None, order: List[OrderItem] | None = None, filter_operator: str | None = None, retired_only: bool = False, include_archived_projects: bool = True, additional_filter_presets: List[Dict[str, Any]] | None = None) → BaseEntity | None[source]

Shortcut for find() with limit=1 so it returns a single result.

>>> sg.find_one("Asset", [["id", "is", 32]], ["id", "code", "sg_status_list"])
{'code': 'Gopher', 'id': 32, 'sg_status_list': 'ip', 'type': 'Asset'}

Parameters:

entity_type (str) – Shotgun entity type as a string to find.
filters (list) –
list of filters to apply to the query.

See also

Filter Syntax
fields (list) – Optional list of fields to include in each entity record returned. Defaults to ["id"].
order (list) –
Optional list of fields to order the results by. List has the format:
```
[
    {'field_name':'foo', 'direction':'asc'},
    {'field_name':'bar', 'direction':'desc'}
]
```
Defaults to sorting by id in ascending order.
filter_operator (str) – Operator to apply to the filters. Supported values are "all" and "any". These are just another way of defining if the query is an AND or OR query. Defaults to "all".
retired_only (bool) – Optional boolean when True will return only entities that have been retired. Defaults to False which returns only entities which have not been retired. There is no option to return both retired and non-retired entities in the same query.
include_archived_projects (bool) – Optional boolean flag to include entities whose projects have been archived. Defaults to True.
additional_filter_presets (list) –
Optional list of presets to further filter the result set, list has the form:
```
[{
    "preset_name": <preset_name>,
    <optional_param1>: <optional_value1>,
    ...
}]
```
Note that these filters are ANDed together and ANDed with the ‘filter’ argument.

For details on supported presets and the format of this parameter see Additional Filter Presets

Returns:

Dictionary representing a single matching entity with the requested fields, and the defaults "id" and "type" which are always included.

See also

Entity Fields

Return type:

Shotgun.update(entity_type: str, entity_id: int, data: Dict[str, Any], multi_entity_update_modes: Dict[str, Any] | None = None) → BaseEntity[source]

Update the specified entity with the supplied data.

>>> shots = [
...    {'type':'Shot', 'id':'40435'},
...    {'type':'Shot', 'id':'40438'},
...    {'type':'Shot', 'id':'40441'}]
>>> data = {
...    'shots': shots_asset_is_in,
...    'sg_status_list':'rev'}
>>> sg.update("Asset", 55, data)
{'type': 'Shot',
 'id': 55,
 'sg_status_`list`': 'rev',
 'shots': [{'id': 40435, 'name': '100_010', 'type': 'Shot', 'valid': 'valid'},
           {'id': 40438, 'name': '100_040', 'type': 'Shot', 'valid': 'valid'},
           {'id': 40441, 'name': '100_070', 'type': 'Shot', 'valid': 'valid'}]
}

Parameters:

entity_type (str) – Entity type to update.
entity_id (id) – id of the entity to update.
data (dict) – key/value pairs where key is the field name and value is the value to set for that field. This method does not restrict the updating of fields hidden in the web UI via the Project Tracking Settings panel.
multi_entity_update_modes (dict) –
Optional dict indicating what update mode to use when updating a multi-entity link field. The keys in the dict are the fields to set the mode for, and the values from the dict are one of set, add, or remove. Defaults to set.
```
multi_entity_update_modes={"shots": "add", "assets": "remove"}
```

Returns:

Dictionary of the fields updated, with the default keys type and id added as well.

Return type:

Shotgun.delete(entity_type: str, entity_id: int) → bool[source]

Retire the specified entity.

Entities in Shotgun are not “deleted” destructively, they are instead, “retired”. This means they are placed in the trash where they are no longer accessible to users.

The entity can be brought back to life using revive().

>>> sg.delete("Shot", 2557)
True

Parameters:

entity_type (str) – Shotgun entity type to delete.
entity_id (id) – id of the entity to delete.

Returns:

True if the entity was deleted, False otherwise (for example, if the entity was already deleted).

Return type:

bool

Raises:

Fault if entity does not exist (deleted or not).

Shotgun.revive(entity_type: str, entity_id: int) → bool[source]

Revive an entity that has previously been deleted.

>>> sg.revive("Shot", 860)
True

Parameters:

entity_type (str) – Shotgun entity type to revive.
entity_id (int) – id of the entity to revive.

Returns:

True if the entity was revived, False otherwise (e.g. if the entity is not currently retired).

Return type:

bool

Shotgun.batch(requests: List[Dict[str, Any]]) → List[Dict[str, Any]][source]

Make a batch request of several create(), update(), and delete() calls.

All requests are performed within a transaction, so either all will complete or none will.

Ex. Make a bunch of shots:

batch_data = []
for i in range(1,100):
    data = {
        "code": "shot_%04d" % i,
        "project": project
    }
    batch_data.append({"request_type": "create", "entity_type": "Shot", "data": data})
sg.batch(batch_data)

Example output:

[{'code': 'shot_0001',
  'type': 'Shot',
  'id': 3624,
  'project': {'id': 4, 'name': 'Demo Project', 'type': 'Project'}},
 ...
 ... and a bunch more ...
 ...
 {'code': 'shot_0099',
  'type': 'Shot',
  'id': 3722,
  'project': {'id': 4, 'name': 'Demo Project', 'type': 'Project'}}]

Ex. All three types of requests in one batch:

batch_data = [
  {"request_type": "create", "entity_type": "Shot", "data": {"code": "New Shot 1", "project": project}},
  {"request_type": "update", "entity_type": "Shot", "entity_id": 3624, "data": {"code": "Changed 1"}},
  {"request_type": "delete", "entity_type": "Shot", "entity_id": 3624}
]
sg.batch(batch_data)

Example output:

[{'code': 'New Shot 1', 'type': 'Shot', 'id': 3723,
  'project': {'id': 4, 'name': 'Demo Project', 'type': 'Project'}},
 {'code': 'Changed 1', 'type': 'Shot', 'id': 3624},
 True]

Parameters:

requests (list) –

A list of dict’s of the form which have a request_type key and also specifies:

create: entity_type, data dict of fields to set
update: entity_type, entity_id, data dict of fields to set,
and optionally multi_entity_update_modes
delete: entity_type and entity_id

Returns:

A list of values for each operation. Create and update requests return a dict of the fields updated. Delete requests return True if the entity was deleted.

Return type:

Shotgun.summarize(entity_type: str, filters: List | Dict[str, Any], summary_fields: List[Dict[str, str]], filter_operator: str | None = None, grouping: List[GroupingItem] | None = None, include_archived_projects: bool = True) → Dict[str, Any][source]

Summarize field data returned by a query.

This provides the same functionality as the summaries in the UI. You can specify one or more fields to summarize, choose the summary type for each, and optionally group the results which will return summary information for each group as well as the total for the query.

Example: Count all Assets for a Project

>>> sg.summarize(entity_type='Asset',
...              filters = [['project', 'is', {'type':'Project', 'id':4}]],
...              summary_fields=[{'field':'id', 'type':'count'}])
{'groups': [], 'summaries': {'id': 15}}

summaries contains the total summary for the query. Each key is the field summarized and the value is the result of the summary operation for the entire result set.

Note

You cannot perform more than one summary on a field at a time, but you can summarize several different fields in the same call.

Example: Count all Assets for a Project, grouped by sg_asset_type

>>> sg.summarize(entity_type='Asset',
...              filters=[['project', 'is', {'type': 'Project', 'id': 4}]],
...              summary_fields=[{'field': 'id', 'type': 'count'}],
...              grouping=[{'field': 'sg_asset_type', 'type': 'exact', 'direction': 'asc'}])
{'groups': [{'group_name': 'Character','group_value': 'Character', 'summaries': {'id': 3}},
            {'group_name': 'Environment','group_value': 'Environment', 'summaries': {'id': 3}},
            {'group_name': 'Matte Painting', 'group_value': 'Matte Painting', 'summaries': {'id': 1}},
            {'group_name': 'Prop', 'group_value': 'Prop', 'summaries': {'id': 4}},
            {'group_name': 'Vehicle', 'group_value': 'Vehicle', 'summaries': {'id': 4}}],
 'summaries': {'id': 15}}

summaries contains the total summary for the query.
groups contains the summary for each group.
- group_name is the display name for the group.
- group_value is the actual value of the grouping value. This is often the same as group_name but in the case when grouping by entity, the group_name may be PuppyA and the group_value would be {'type':'Asset','id':922,'name':'PuppyA'}.
- summaries contains the summary calculation dict for each field requested.

Example: Count all Tasks for a Sequence and find the latest due_date

>>> sg.summarize(entity_type='Task',
...              filters = [
...                 ['entity.Shot.sg_sequence', 'is', {'type':'Sequence', 'id':2}],
...                 ['sg_status_list', 'is_not', 'na']],
...              summary_fields=[{'field':'id', 'type':'count'},
...                              {'field':'due_date','type':'latest'}])
{'groups': [], 'summaries': {'due_date': '2013-07-05', 'id': 30}}

This shows that the there are 30 Tasks for Shots in the Sequence and the latest due_date of any Task is 2013-07-05.

Example: Count all Tasks for a Sequence, find the latest due_date and group by Shot

>>> sg.summarize(entity_type='Task',
...              filters = [
...                 ['entity.Shot.sg_sequence', 'is', {'type': 'Sequence', 'id': 2}],
...                 ['sg_status_list', 'is_not', 'na']],
...              summary_fields=[{'field': 'id', 'type': 'count'}, {'field': 'due_date', 'type': 'latest'}],
...              grouping=[{'field': 'entity', 'type': 'exact', 'direction': 'asc'}]))
{'groups': [{'group_name': 'shot_010',
             'group_value': {'id': 2, 'name': 'shot_010', 'type': 'Shot', 'valid': 'valid'},
             'summaries': {'due_date': '2013-06-18', 'id': 10}},
            {'group_name': 'shot_020',
             'group_value': {'id': 3, 'name': 'shot_020', 'type': 'Shot', 'valid': 'valid'},
             'summaries': {'due_date': '2013-06-28', 'id': 10}},
            {'group_name': 'shot_030',
             'group_value': {'id': 4, 'name': 'shot_030', 'type': 'Shot', 'valid': 'valid'},
             'summaries': {'due_date': '2013-07-05', 'id': 10}}],
 'summaries': {'due_date': '2013-07-05', 'id': 30}}

This shows that the there are 30 Tasks for Shots in the Sequence and the latest due_date of any Task is 2013-07-05. Because the summary is grouped by entity, we can also see the summaries for each Shot returned. Each Shot has 10 Tasks and the latest due_date for each Shot. The difference between group_name and group_value is highlighted in this example as the name of the Shot is different from its value.

Example: Count all Tasks for a Sequence, find the latest due_date, group by Shot and Pipeline Step

>>> sg.summarize(entity_type='Task',
...                 filters = [
...                    ['entity.Shot.sg_sequence', 'is', {'type': 'Sequence', 'id': 2}],
...                    ['sg_status_list', 'is_not', 'na']],
...                 summary_fields=[{'field': 'id', 'type': 'count'},
...                                 {'field': 'due_date', 'type': 'latest'}],
...                 grouping=[{'field': 'entity', 'type': 'exact', 'direction': 'asc'},
...                           {'field': 'step', 'type': 'exact', 'direction': 'asc'}])
{'groups': [{'group_name': 'shot_010',
             'group_value': {'id': 2, 'name': 'shot_010', 'type': 'Shot', 'valid': 'valid'},
             'groups': [{'group_name': 'Client',
                         'group_value': {'id': 1, 'name': 'Client', 'type': 'Step', 'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-04', 'id': 1}},
                        {'group_name': 'Online',
                         'group_value': {'id': 2, 'name': 'Online', 'type': 'Step', 'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-05', 'id': 1}},
                        ...
                        ... truncated for brevity
                        ...
                        {'group_name': 'Comp',
                         'group_value': {'id': 8, 'name': 'Comp', 'type': 'Step', 'valid': 'valid'},
                         'summaries': {'due_date': '2013-06-18', 'id': 1}}],
             'summaries': {'due_date': '2013-06-18', 'id': 10}},
            {'group_name': 'shot_020',
             'group_value': {'id': 3, 'name': 'shot_020', 'type': 'Shot', 'valid': 'valid'},
             'groups': [{'group_name': 'Client',
                         'group_value': {'id': 1, 'name': 'Client', 'type': 'Step', 'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-15', 'id': 1}},
                        {'group_name': 'Online',
                         'group_value': {'id': 2, 'name': 'Online', 'type': 'Step', 'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-16', 'id': 1}},
                        ...
                        ... truncated for brevity
                        ...
                        {'group_name': 'Comp',
                         'group_value': {'id': 8, 'name': 'Comp', 'type': 'Step', 'valid': 'valid'},
                         'summaries': {'due_date': '2013-06-28', 'id': 1}}],
             'summaries': {'due_date': '2013-06-28', 'id': 10}},
            {'group_name': 'shot_030',
             'group_value': {'id': 4, 'name': 'shot_030', 'type': 'Shot', 'valid': 'valid'},
             'groups': [{'group_name': 'Client',
                         'group_value': {'id': 1, 'name': 'Client', 'type': 'Step', 'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-20', 'id': 1}},
                        {'group_name': 'Online',
                         'group_value': {'id': 2, 'name': 'Online', 'type': 'Step', 'valid': 'valid'},
                         'summaries': {'due_date': '2013-05-21', 'id': 1}},
                        ...
                        ... truncated for brevity
                        ...
                        {'group_name': 'Comp',
                         'group_value': {'id': 8, 'name': 'Comp', 'type': 'Step', 'valid': 'valid'},
                         'summaries': {'due_date': '2013-07-05', 'id': 1}}],
             'summaries': {'due_date': '2013-07-05', 'id': 10}}],
'summaries': {'due_date': '2013-07-05', 'id': 30}}

When grouping my more than one field, the grouping structure is repeated for each sub-group and summary values are returned for each group on each level.

Parameters:

entity_type (str) – The entity type to summarize
filters (list) – A list of conditions used to filter the find query. Uses the same syntax as find() method.
summary_fields (list) –
A list of dictionaries with the following keys:

field:

The internal Shotgun field name you are summarizing.

type:

The type of summary you are performing on the field. Summary types can be any of record_count, count, sum, maximum, minimum, average, earliest, latest, percentage, status_percentage, status_list, checked, unchecked depending on the type of field you’re summarizing.
filter_operator (str) – Operator to apply to the filters. Supported values are "all" and "any". These are just another way of defining if the query is an AND or OR query. Defaults to "all".
grouping (list) –
Optional list of dicts with the following keys:

field:

a string indicating the internal Shotgun field name on entity_type to group results by.

type:

A string indicating the type of grouping to perform for each group. Valid types depend on the type of field you are grouping on and can be one of exact, tens, hundreds, thousands, tensofthousands, hundredsofthousands, millions, day, week, month, quarter,``year``, clustered_date, oneday, fivedays, entitytype, firstletter.

direction:

A string that sets the order to display the grouped results. Valid options are asc and desc. Defaults to asc.

Returns:

dictionary containing grouping and summaries keys.

Return type:

Shotgun.note_thread_read(note_id: int, entity_fields: Dict[str, Any] | None = None) → List[Dict[str, Any]][source]

Return the full conversation for a given note, including Replies and Attachments.

Returns a complex data structure on the following form:

[{'content': 'Please add more awesomeness to the color grading.',
  'created_at': '2015-07-14 21:33:28 UTC',
  'created_by': {'id': 38,
                 'name': 'John Pink',
                 'status': 'act',
                 'type': 'HumanUser',
                 'valid': 'valid'},
  'id': 6013,
  'type': 'Note'},
 {'created_at': '2015-07-14 21:33:32 UTC',
  'created_by': {'id': 38,
                 'name': 'John Pink',
                 'status': 'act',
                 'type': 'HumanUser',
                 'valid': 'valid'},
  'id': 159,
  'type': 'Attachment'},
 {'content': 'More awesomeness added',
  'created_at': '2015-07-14 21:54:51 UTC',
  'id': 5,
  'type': 'Reply',
  'user': {'id': 38,
           'name': 'David Blue',
           'status': 'act',
           'type': 'HumanUser',
           'valid': 'valid'}}]

The list is returned in descending chronological order.

If you wish to include additional fields beyond the ones that are returned by default, you can specify these in an entity_fields dictionary. This dictionary should be keyed by entity type and each key should contain a list of fields to retrieve, for example:

{ "Note":       ["created_by.HumanUser.image",
                 "addressings_to",
                 "playlist",
                 "user" ],
  "Reply":      ["content"],
  "Attachment": ["filmstrip_image",
                "local_storage",
                "this_file",
                "image"]
}

Parameters:

note_id (int) – The id for the note to be retrieved
entity_fields (dict) – Additional fields to retrieve as part of the request. See above for details.

Returns:

A list of dictionaries. See above for example.

Return type:

Shotgun.text_search(text: str, entity_types: Dict[str, Any], project_ids: List | None = None, limit: int | None = None) → Dict[str, Any][source]

Search across the specified entity types for the given text.

This method can be used to implement auto completion or a Shotgun global search. The method requires a text input phrase that is at least three characters long, or an exception will be raised.

Several ways to limit the results of the query are available:

Using the project_ids parameter, you can provide a list of Project ids to search across. Leaving this at its default value of None will search across all Shotgun data.
You need to define which subset of entity types to search using the entity_types parameter. Each of these entity types can be associated with a filter query to further reduce the list of matches. The filter list is using the standard filter syntax used by for example the find() method.

Example: Constrain the search to all Tasks but Character Assets only

>>> entity_types = {
...     "Asset": [["sg_asset_type", "is", "Character"]],
...     "Task": []
... }
>>> sg.text_search("bunny", entity_types)
{'matches': [{'id': 734,
              'type': 'Asset',
              'name': 'Bunny',
              'project_id': 65,
              'image': 'https://...',
              'links': ['', ''],
              'status': 'fin'},
              ...
              {'id': 558,
               'type': 'Task'
               'name': 'FX',
               'project_id': 65,
               'image': 'https://...',
               'links': ['Shot', 'bunny_010_0010'],
               'status': 'fin'}],
    'terms': ['bunny']}

The links field will contain information about any linked entity. This is useful when, for example, presenting Tasks and you want to display what Shot or Asset the Task is associated with.

Parameters:

text (str) – Text to search for. This must be at least three characters long, or an exception will be raised.
entity_types (dict) – Dictionary to specify which entity types to search across. See above for usage examples.
project_ids (list) – List of Projects to search. By default, all projects will be searched.
limit (int) – Specify the maximum number of matches to return.

Returns:

A complex dictionary structure, see above for example.

Return type:

Shotgun.update_project_last_accessed(project: Dict[str, Any], user: Dict[str, Any] | None = None) → None[source]

Update a Project’s last_accessed_by_current_user field to the current timestamp.

This helps keep track of the recent Projects each user has worked on and enables scripts and apps to use this information to display “Recent Projects” for users as a convenience.

New in version Requires: Shotgun v5.3.20+

>>> sg.update_project_last_accessed({"type": "Project", "id": 66},
...                                 {"type": "HumanUser", "id": 43})

Parameters:

project (dict) – Standard Project entity dictionary
user (dict) – Standard user entity dictionary. This is optional if the current API instance is using user-based authenitcation, or has specified sudo_as_login. In these cases, if user is not provided, the sudo_as_login value or login value from the current instance will be used instead.

Shotgun.work_schedule_read(start_date: str, end_date: str, project: Dict[str, Any] | None = None, user: Dict[str, Any] | None = None) → Dict[str, Any][source]

Return the work day rules for a given date range.

New in version 3.0.9: Requires Shotgun server v3.2.0+

This returns the defined WorkDayRules between the start_date and end_date inclusive as a dict where the key is the date and the value is another dict describing the rule for that date.

Rules are represented by a dict with the following keys:

Description:

the description entered into the work day rule exception if applicable.

Reason:

one of six options:

STUDIO_WORK_WEEK: standard studio schedule applies
STUDIO_EXCEPTION: studio-wide exception applies
PROJECT_WORK_WEEK: standard project schedule applies
PROJECT_EXCEPTION: project-specific exception applies
USER_WORK_WEEK: standard user work week applies
USER_EXCEPTION: user-specific exception applies

Working:

boolean indicating whether it is a “working” day or not.

>>> sg.work_schedule_read("2015-12-21", "2015-12-25")
{'2015-12-21': {'description': None,
                'reason': 'STUDIO_WORK_WEEK',
                'working': True},
 '2015-12-22': {'description': None,
                'reason': 'STUDIO_WORK_WEEK',
                'working': True},
 '2015-12-23': {'description': None,
                'reason': 'STUDIO_WORK_WEEK',
                'working': True},
 '2015-12-24': {'description': 'Closed for Christmas Eve',
                'reason': 'STUDIO_EXCEPTION',
                'working': False},
 '2015-12-25': {'description': 'Closed for Christmas',
                'reason': 'STUDIO_EXCEPTION',
                'working': False}}

Parameters:

start_date (str) – Start date of date range. YYYY-MM-DD
end_date (str) – End date of date range. YYYY-MM-DD
project (dict) – Optional Project entity to query WorkDayRules for.
user (dict) – Optional HumanUser entity to query WorkDayRules for.

Returns:

Complex dict containing each date and the WorkDayRule defined for that date between the start_date and end date inclusive. See above for details.

Return type:

Shotgun.work_schedule_update(date: str, working: bool, description: str | None = None, project: Dict[str, Any] | None = None, user: Dict[str, Any] | None = None, recalculate_field: str | None = None) → Dict[str, Any][source]

Update the work schedule for a given date.

New in version 3.0.9: Requires Shotgun server v3.2.0+

If neither project nor user are passed in, the studio work schedule will be updated. project and user can only be used exclusively of each other.

>>> sg.work_schedule_update ("2015-12-31", working=False,
...                          description="Studio closed for New Years Eve", project=None,
...                          user=None, recalculate_field=None)
{'date': '2015-12-31',
 'description': "Studio closed for New Years Eve",
 'project': None,
 'user': None,
 'working': False}

Parameters:

date (str) – Date of WorkDayRule to update. YYY-MM-DD
working (bool) – Indicates whether the day is a working day or not.
description (str) – Optional reason for time off.
project (dict) – Optional Project entity to assign the rule to. Cannot be used with the user param.
user (dict) – Optional HumanUser entity to assign the rule to. Cannot be used with the project param.
recalculate_field (str) – Optional schedule field that will be recalculated on Tasks when they are affected by a change in working schedule. Options are due_date or duration. Defaults to the value set in the Shotgun web application’s Site Preferences.

Returns:

dict containing key/value pairs for each value of the work day rule updated.

Return type:

Details About Working With Files

Shotgun.preferences_read(prefs: List | None = None) → Dict[str, Any][source]

Get a subset of the site preferences.

>>> sg.preferences_read()
{
    "pref_name": "pref value"
}

Parameters:: prefs (list) – An optional list of preference names to return.
Returns:: Dictionary of preferences and their values.
Return type:: dict

Shotgun.export_page(page_id, format, layout_name=None)[source]

Export the specified page to the given format.

This method allows you to export a page to CSV.

Respective layout or page should be marked as API Exportable in the Flow Production Tracking UI.

If layout_name is not passed in, the default layout name will be used.

For more information, see documentation .

>>> sg.export_page(12345, "csv", layout_name="My Layout")
"ID,Name,Status\n1,Shot 001,ip\n2,    Shot 002,rev\n"
>>> sg.export_page(12345, "csv")
"ID,Name,Status\n1,Shot 001,ip\n2,Shot 002,rev\n"

Parameters:

page_id (int) – The ID of the page to export.
format (str) – The format to export the page to. Supported format is "csv".
layout_name (str) – Optional layout name. This should be the name of the layout seen in the Flow Production Tracking UI.

Returns:

string containing data of the given page.

Return type:

string

Working With Files

Methods that handle uploading and downloading files including thumbnails.

See also

Shotgun.upload(entity_type: str, entity_id: int, path: str, field_name: str | None = None, display_name: str | None = None, tag_list: str | None = None) → int[source]

Upload a file to the specified entity.

Creates an Attachment entity for the file in Shotgun and links it to the specified entity. You can optionally store the file in a field on the entity, change the display name, and assign tags to the Attachment.

Note

Make sure to have retries for file uploads. Failures when uploading will occasionally happen. When it does, immediately retrying to upload usually works

>>> mov_file = '/data/show/ne2/100_110/anim/01.mlk-02b.mov'
>>> sg.upload("Shot", 423, mov_file, field_name="sg_latest_quicktime",
...           display_name="Latest QT")
72

Parameters:

entity_type (str) – Entity type to link the upload to.
entity_id (int) – Id of the entity to link the upload to.
path (str) – Full path to an existing non-empty file on disk to upload.
field_name (str) – The internal Shotgun field name on the entity to store the file in. This field must be a File/Link field type.
display_name (str) – The display name to use for the file. Defaults to the file name.
tag_list (str) – comma-separated string of tags to assign to the file.

Returns:

Id of the Attachment entity that was created for the image.

Return type:

Raises:

ShotgunError on upload failure.

Shotgun.upload_thumbnail(entity_type: str, entity_id: int, path: str, **kwargs: Any) → int[source]

Upload a file from a local path and assign it as the thumbnail for the specified entity.

Note

Images will automatically be re-sized on the server to generate a size-appropriate image file. However, the original file is retained as well and is accessible when you click on the thumbnail image in the web UI. If you are using a local install of Shotgun and have not enabled S3, this can eat up disk space if you’re uploading really large source images for your thumbnails.

You can un-set (aka clear) a thumbnail on an entity using the update() method and setting the image field to None. This will also unset the filmstrip_thumbnail field if it is set.

Supported image file types include .jpg` and ``.png (preferred) but will also accept. .gif`, .tif, .tiff, .bmp, .exr, .dpx, and .tga.

This method wraps over upload(). Additional keyword arguments passed to this method will be forwarded to the upload() method.

Parameters:

entity_type (str) – Entity type to set the thumbnail for.
entity_id (int) – Id of the entity to set the thumbnail for.
path (str) – Full path to the thumbnail file on disk.

Returns:

Id of the new attachment

Return type:

Shotgun.upload_filmstrip_thumbnail(entity_type: str, entity_id: int, path: str, **kwargs: Any) → int[source]

Upload filmstrip thumbnail to specified entity.

New in version 3.0.9: Requires Shotgun server v3.1.0+

Uploads a file from a local directory and assigns it as the filmstrip thumbnail for the specified entity. The image must be a horizontal strip of any number of frames that are exactly 240 pixels wide. Therefore the whole strip must be an exact multiple of 240 pixels in width. The height can be anything (and will depend on the aspect ratio of the frames). Any image file type that works for thumbnails will work for filmstrip thumbnails.

Filmstrip thumbnails will only be visible in the Thumbnail field on an entity if a regular thumbnail image is also uploaded to the entity. The standard thumbnail is displayed by default as the poster frame. Then, on hover, the filmstrip thumbnail is displayed and updated based on your horizontal cursor position for scrubbing. On mouseout, the default thumbnail is displayed again as the poster frame.

The url for a filmstrip thumbnail on an entity is available by querying for the filmstrip_image field.

You can un-set (aka clear) a thumbnail on an entity using the update() method and setting the image field to None. This will also unset the filmstrip_thumbnail field if it is set.

This method wraps over upload(). Additional keyword arguments passed to this method will be forwarded to the upload() method.

>>> filmstrip_thumbnail = '/data/show/ne2/100_110/anim/01.mlk-02b_filmstrip.jpg'
>>> sg.upload_filmstrip_thumbnail("Version", 27, filmstrip_thumbnail)
87

Parameters:

entity_type (str) – Entity type to set the filmstrip thumbnail for.
entity_id (int) – Id of the entity to set the filmstrip thumbnail for.
path (str) – Full path to the filmstrip thumbnail file on disk.

Returns:

Id of the new Attachment entity created for the filmstrip thumbnail

Return type:

Download the file associated with a Shotgun Attachment.

>>> version = sg.find_one("Version", [["id", "is", 7115]], ["sg_uploaded_movie"])
>>> local_file_path = "/var/tmp/%s" % version["sg_uploaded_movie"]["name"]
>>> sg.download_attachment(version["sg_uploaded_movie"], file_path=local_file_path)
/var/tmp/100b_scene_output_v032.mov

Warning

On older (< v5.1.0) Shotgun versions, non-downloadable files on Shotgun don’t raise exceptions, they cause a server error which returns a 200 with the page content.

Parameters:

attachment (dict) –
Usually a dictionary representing an Attachment entity. The dictionary should have a url key that specifies the download url. Optionally, the dictionary can be a standard entity hash format with id and type keys as long as "type"=="Attachment". This is only supported for backwards compatibility (#22150).

If an int value is passed in, the Attachment entity with the matching id will be downloaded from the Shotgun server.
file_path (str) – Optional file path to write the data directly to local disk. This avoids loading all of the data in memory and saves the file locally at the given path.
attachment_id (id) –
(deprecated) Optional id of the Attachment entity in Shotgun to download.

Returns:

If file_path is provided, returns the path to the file on disk. If file_path is None, returns the actual data of the file, as bytes.

Return type:

str | bytes

Shotgun.get_attachment_download_url(attachment: int | dict[str, Any] | None) → str[source]

Return the URL for downloading provided Attachment.

Parameters:

attachment (mixed) –

Usually a dict representing An Attachment entity in Shotgun to return the download url for. If the url key is present, it will be used as-is for the download url. If the url key is not present, a url will be constructed pointing at the current Shotgun server for downloading the Attachment entity using the id.

If None is passed in, it is silently ignored in order to avoid raising an error when results from a find() are passed off to download_attachment()

Note

Support for passing in an int representing the Attachment id is deprecated

Returns:: the download URL for the Attachment or None if None was passed to attachment parameter.
Return type:: str

Shotgun.share_thumbnail(entities: List[Dict[str, Any]], thumbnail_path: str | None = None, source_entity: BaseEntity | None = None, filmstrip_thumbnail: bool = False, **kwargs: Any) → int[source]

Associate a thumbnail with more than one Shotgun entity.

New in version 3.0.9: Requires Shotgun server v4.0.0+

Share the thumbnail from between entities without requiring uploading the thumbnail file multiple times. You can use this in two ways:

Upload an image to set as the thumbnail on multiple entities.
Update multiple entities to point to an existing entity’s thumbnail.

Note

When sharing a filmstrip thumbnail, it is required to have a static thumbnail in place before the filmstrip will be displayed in the Shotgun web UI. If the thumbnail is still processing and is using a placeholder, this method will error.

Simple use case:

>>> thumb = '/data/show/ne2/100_110/anim/01.mlk-02b.jpg'
>>> e = [{'type': 'Version', 'id': 123}, {'type': 'Version', 'id': 456}]
>>> sg.share_thumbnail(entities=e, thumbnail_path=thumb)
4271

>>> e = [{'type': 'Version', 'id': 123}, {'type': 'Version', 'id': 456}]
>>> sg.share_thumbnail(entities=e, source_entity={'type':'Version', 'id': 789})
4271

Parameters:

entities (list) –
The entities to update to point to the shared thumbnail provided in standard entity dict format:
```
[{'type': 'Version', 'id': 123},
 {'type': 'Version', 'id': 456}]
```
thumbnail_path (str) – The full path to the local thumbnail file to upload and share. Required if source_entity is not provided.
source_entity (dict) – The entity whos thumbnail will be the source for sharing. Required if source_entity is not provided.
filmstrip_thumbnail (bool) – True to share the filmstrip thumbnail. False to share the static thumbnail. Defaults to False.

Returns:

id of the Attachment entity representing the source thumbnail that is shared.

Return type:

Raises:

ShotgunError if not supported by server version or improperly called, or ShotgunThumbnailNotReady if thumbnail is still pending.

Activity Stream

Methods that relate to the activity stream and following of entities in Flow Production Tracking.

Shotgun.activity_stream_read(entity_type: str, entity_id: int, entity_fields: Dict[str, Any] | None = None, min_id: int | None = None, max_id: int | None = None, limit: int | None = None) → Dict[str, Any][source]

Retrieve activity stream data from Shotgun.

This data corresponds to the data that is displayed in the Activity tab for an entity in the Shotgun Web UI.

A complex data structure on the following form will be returned from Shotgun:

{'earliest_update_id': 50,
 'entity_id': 65,
 'entity_type': 'Project',
 'latest_update_id': 79,
 'updates': [{'created_at': '2015-07-15 11:06:55 UTC',
              'created_by': {'id': 38,
                             'image': '6641',
                             'name': 'John Smith',
                             'status': 'act',
                             'type': 'HumanUser'},
              'id': 79,
              'meta': {'entity_id': 6004,
                       'entity_type': 'Version',
                       'type': 'new_entity'},
              'primary_entity': {'id': 6004,
                                 'name': 'Review_turntable_v2',
                                 'status': 'rev',
                                 'type': 'Version'},
              'read': False,
              'update_type': 'create'},
             {...},
            ]
}

The main payload of the return data can be found inside the ‘updates’ key, containing a list of dictionaries. This list is always returned in descending date order. Each item may contain different fields depending on their update type. The primary_entity key represents the main Shotgun entity that is associated with the update. By default, this entity is returned with a set of standard fields. By using the entity_fields parameter, you can extend the returned data to include additional fields. If for example you wanted to return the asset type for all assets and the linked sequence for all Shots, pass the following entity_fields:

{"Shot": ["sg_sequence"], "Asset": ["sg_asset_type"]}

Deep queries can be used in this syntax if you want to traverse into connected data.

Parameters:

entity_type (str) – Entity type to retrieve activity stream for
entity_id (int) – Entity id to retrieve activity stream for
entity_fields (list) – List of additional fields to include. See above for details
max_id (int) – Do not retrieve ids greater than this id. This is useful when implementing paging.
min_id (int) – Do not retrieve ids lesser than this id. This is useful when implementing caching of the event stream data and you want to “top up” an existing cache.
limit (int) – Limit the number of returned records. If not specified, the system default will be used.

Returns:

A complex activity stream data structure. See above for details.

Return type:

Shotgun.follow(user: Dict[str, Any], entity: Dict[str, Any]) → Dict[str, Any][source]

Add the entity to the user’s followed entities.

If the user is already following the entity, the method will succeed but nothing will be changed on the server-side.

>>> sg.follow({"type": "HumanUser", "id": 42}, {"type": "Shot", "id": 2050})
{'followed': True, 'user': {'type': 'HumanUser', 'id': 42},
 'entity': {'type': 'Shot', 'id': 2050}}

Parameters:

user (dict) – User entity that will follow the entity.
entity (dict) – Shotgun entity to be followed.

Returns:

dict with "followed": True as well as key/values for the params that were passed in.

Return type:

Shotgun.unfollow(user: Dict[str, Any], entity: Dict[str, Any]) → Dict[str, Any][source]

Remove entity from the user’s followed entities.

This does nothing if the user is not following the entity.

>>> sg.unfollow({"type": "HumanUser", "id": 42}, {"type": "Shot", "id": 2050})
{'entity': {'type': 'Shot', 'id': 2050}, 'user': {'type': 'HumanUser', 'id': 42},
 'unfollowed': True}

Parameters:

user (dict) – User entity that will unfollow the entity.
entity (dict) – Entity to be unfollowed

Returns:

dict with "unfollowed": True as well as key/values for the params that were passed in.

Return type:

Shotgun.followers(entity: Dict[str, Any]) → List[Dict[str, Any]][source]

Return all followers for an entity.

>>> sg.followers({"type": "Shot", "id": 2050})
[{'status': 'act', 'valid': 'valid', 'type': 'HumanUser', 'name': 'Richard Hendriks',
  'id': 42},
 {'status': 'act', 'valid': 'valid', 'type': 'HumanUser', 'name': 'Bertram Gilfoyle',
  'id': 33},
 {'status': 'act', 'valid': 'valid', 'type': 'HumanUser', 'name': 'Dinesh Chugtai',
  'id': 57}]

Parameters:: entity (dict) – Entity to find followers of.
Returns:: list of dicts representing each user following the entity
Return type:: list
Versionadded:

Shotgun.following(user: Dict[str, Any], project: Dict[str, Any] | None = None, entity_type: str | None = None) → List[BaseEntity][source]

Return all entity instances a user is following.

Optionally, a project and/or entity_type can be supplied to restrict returned results.

>>> user = {"type": "HumanUser", "id": 1234}
>>> project = {"type": "Project", "id": 1234}
>>> entity_type = "Task"
>>> sg.following(user, project=project, entity_type=entity_type)
[{"type":"Task", "id":1},
 {"type":"Task", "id":2},
 {"type":"Task", "id":3}]

Parameters:

user (dict) – Find what this person is following.
project (dict) – Optional filter to only return results from a specific project.
entity_type (str) – Optional filter to only return results from one entity type.

Returns:

list of dictionaries, each containing entity type & id’s being followed.

Return type:

Working with the Shotgun Schema

Methods allow you to introspect and modify the Shotgun schema.

Shotgun.schema_entity_read(project_entity: BaseEntity | None = None) → Dict[str, Dict[str, Any]][source]

Return all active entity types, their display names, and their visibility.

If the project parameter is specified, the schema visibility for the given project is being returned. If the project parameter is omitted or set to None, a full listing is returned where per-project entity type visibility settings are not considered.

>>> sg.schema_entity_read()
{'ActionMenuItem': {'name': {'editable': False, 'value': 'Action Menu Item'},
                    'visible': {'editable': False, 'value': True}},
 'ApiUser': {'name': {'editable': False, 'value': 'Script'},
             'visible': {'editable': False, 'value': True}},
 'AppWelcomeUserConnection': {'name': {'editable': False,
                                       'value': 'App Welcome User Connection'},
                              'visible': {'editable': False, 'value': True}},
 'Asset': {'name': {'editable': False, 'value': 'Asset'},
           'visible': {'editable': False, 'value': True}},
 'AssetAssetConnection': {'name': {'editable': False,
                                   'value': 'Asset Asset Connection'},
                          'visible': {'editable': False, 'value': True}},
 '...'
}

Parameters:: project_entity (dict) – Optional Project entity specifying which project to return the listing for. If omitted or set to None, per-project visibility settings are not taken into consideration and the global list is returned. Example: {'type': 'Project', 'id': 3}
Returns:: dict of Entity Type to dict containing the display name.
Return type:: dict

Note

The returned display names for this method will be localized when the localize Shotgun config property is set to True. See Localization for more information.

Shotgun.schema_field_read(entity_type: str, field_name: str | None = None, project_entity: BaseEntity | None = None) → Dict[str, Dict[str, Any]][source]

Get schema for all fields on the specified entity type or just the field name specified if provided.

Note

Unlike how the results of a find() can be pumped into a create() or update(), the results of schema_field_read() are not compatible with the format used for schema_field_create() or schema_field_update(). If you need to pipe the results from schema_field_read() into a schema_field_create() or schema_field_update(), you will need to reformat the data in your script.

Note

If you don’t specify a project_entity, everything is reported as visible.

Note

The returned display names for this method will be localized when the localize Shotgun config property is set to True. See Localization for more information.

>>> sg.schema_field_read('Asset', 'shots')
{'shots': {'data_type': {'editable': False, 'value': 'multi_entity'},
           'description': {'editable': True, 'value': ''},
           'editable': {'editable': False, 'value': True},
           'entity_type': {'editable': False, 'value': 'Asset'},
           'mandatory': {'editable': False, 'value': False},
           'name': {'editable': True, 'value': 'Shots'},
           'properties': {'default_value': {'editable': False,
                                            'value': None},
                          'summary_default': {'editable': True,
                                              'value': 'none'},
                          'valid_types': {'editable': True,
                                          'value': ['Shot']}},
           'unique': {'editable': False, 'value': False},
           'visible': {'editable': False, 'value': True}}}

Parameters:

entity_type (str) – Entity type to get the schema for.
field_name (str) – Optional internal Shotgun name of the field to get the schema definition for. If this parameter is excluded or set to None, data structures of all fields will be returned. Defaults to None. Example: sg_temp_field.
project_entity (dict) – Optional Project entity specifying which project to return the listing for. If omitted or set to None, per-project visibility settings are not taken into consideration and the global list is returned. Example: {'type': 'Project', 'id': 3}

Returns:

a nested dict object containing a key/value pair for the field_name specified and its properties, or if no field_name is specified, for all the fields of the entity_type. Properties that are 'editable': True, can be updated using the schema_field_update() method.

Return type: