API Usage Tips

Below is a list of helpful tips when using the Shotgun API. We have tried to make the API very simple to use with predictable results while remaining a powerful tool to integrate with your pipeline. However, there's always a couple of things that crop up that our users might not be aware of. Those are the types of things you'll find below. We'll be adding to this document over time as new questions come up from our users that exhibit these types of cases.

Entity Fields

When you do a find() that returns a field of type entity or multi-entity (for example the 'assets' column on Shot), the entities are returned in a standard hash (dict) format:

    {'type':'Asset', 'name':'redBall', 'id':1}

For each entity returned, you will get a 'type', 'name', and 'id' key. This does not mean there are fields named 'type' and 'name' on the Asset. This is only used to provide a consistent way to represent entities returned via the API.

type: the entity type (CamelCase)
name: the display name of the entity. For most entity types this is the field named code but not always. For example, on the Ticket and Delivery entities the name key would contain the value of the title field.

Shotgun UI fields not available via the API

Summary type fields like Query Fields and Pipeline Step summary fields are currently only available via the UI. Some other fields may not work as expected through the API because they are "display only" fields made available for convenience and are only available in the browser UI.

HumanUser

• name: This is a UI-only field that is a combination of the 'firstname' + ' ' + 'lastname'.

Shot

• Smart Cut Fields: These fields are available only in the browser UI. You can read more about smart cut fields and the API at Smart-Cut-Fields
  • smart_cut_in
  • smart_cut_out
  • smart_cut_duration
  • smart_cut_summary_display
  • smart_duration_summary_display
  • smart_head_in
  • smart_head_out
  • smart_head_duration
  • smart_tail_in
  • smart_tail_out
  • smart_tail_duration
  • smart_working_duration

Pipeline Step summary fields on entities

The Pipeline Step summary fields on entities that have Tasks aren't currently available via the API and are calculated on the client side in the UI. These fields are like step_0, or step_13. Note that the Pipeline Step entity itself is available via the API as the entity type 'Step'.

Query Fields

Query fields are also summary fields like Pipeline Steps, the query is run from the client side UI and therefore is not currently supported in the API.

Audit Fields

You can set the created_by and created_at fields via the API at creation time. This is often useful for when you're importing or migrating data from another source and want to keep the history in tact. However, you cannot set the updated_by and updated_at fields. These are automatically set whenever an entity is created or updated.

Logging

The wrapper uses standard python logging. The default level is set to ERROR, if you wish to see more verbose output, the level can be set in the calling script:

    import logging
    sg_log = logging.getLogger('shotgun_api3')
    sg_log.setLevel(logging.DEBUG)