InstanceService.GetInstanceFilesAsync

Reference

Task<PagedData<InstanceFile>> GetInstanceFilesAsync(Guid instanceId, FileQuery fileQuery)

Use GetInstanceFilesAsync to retrieve files attached to a specific Protrak instance. The result set can be paged, sorted, filtered by category, and filtered by one or more file types.

Parameters

• Guid instanceId: The unique identifier of the instance whose files should be returned.
• FileQuery fileQuery:
  • Enum.FileType? FileType: Optional single file type enum filter.
  • int Skip: Number of records to skip before paging. Optional; default is 0.
  • int Take: Maximum number of records to return. Optional; default is 100.
  • string SortBy: Property name used for sorting the result. Optional.
  • bool IsSortByDescending: When true, sort in descending order. Optional; default is false.
  • FileCategory? Category: Optional file category filter.
    • Attachment
    • Attribute
    • Message
    • Reply
  • string[]? FileTypes: Optional array of file type names to filter results. When supplied, only files whose fileType matches one of the provided values are returned. Matching is case-insensitive.

Returns

• PagedData<InstanceFile>:
  • int TotalCount: Total number of matching files after filters are applied.
  • int Skip: The skip value that was used.
  • int Take: The take value that was used.
  • IEnumerable<InstanceFile> Items: The returned files. Each item includes file metadata such as fileName, fileType,category and download URL metadata.

Caveats

• If FileTypes is omitted or empty, the existing behavior is preserved and all attachments are returned.
• If FileTypes contains one or more values, filtering is applied before sorting and paging.
• TotalCount reflects the number of matching files before pagination.
• File type matching is case-insensitive.
• FileTypes supports multiple values, while FileType is a single-value enum filter.
• Category filters by the file category defined in FileCategory:
  • Attachment
  • Attribute
  • Message
  • Reply

Usage

• Retrieve all files

var fileQuery = new FileQuery
{
    Skip = 0,
    Take = 100
};

var files = await InstanceService.GetInstanceFilesAsync(instanceId, fileQuery);

• Retrieve files of a single type

var fileQuery = new FileQuery
{
    FileTypes = new[] { "Standardpng" }
};

var pngFiles = await InstanceService.GetInstanceFilesAsync(instanceId, fileQuery);

• Retrieve files of multiple types

var fileQuery = new FileQuery
{
    FileTypes = new[] { "Standardpng", "Standardjpg" }
};

var imageFiles = await InstanceService.GetInstanceFilesAsync(instanceId, fileQuery);

• Retrieve files filtered by category and sorted

var fileQuery = new FileQuery
{
    Category = FileCategory.Attachment,
    SortBy = "LastModified",
    IsSortByDescending = true,
    Skip = 0,
    Take = 25
};

var attachments = await InstanceService.GetInstanceFilesAsync(instanceId, fileQuery);

Example Response

{
    "totalCount": 1,
    "skip": 0,
    "take": 2147483647,
    "items": [
        {
            "id":  "00000000-0000-0000-0000-000000000000",
            "fileId":  "00000000-0000-0000-0000-000000000000",
            "thumbnailId": "00000000-0000-0000-0000-000000000000",
            "fileName": "STANDARDTaskTasksDashboard_TEST.csv",
            "type": "Document",
            "modifiedBy": "Admin User",
            "lastModified": "2026-07-14T09:55:25.383Z",
            "category": "Attachment",
            "fileType": "Standardcsv"
        }
    ]
}