Overview

You can list multiple or single cases with FogBugz API using two commands:

• cmd=listCases - uses a saved filter
• cmd=search - needs a search criteria

Both can be used for listing in one step also the case contents by adding the required columns as a parameter. Both are limited to a maximum of 100.000 results, and this limit cannot be increased.

FogBugz supports both XML API and JSON API using the same parameters.

Information

Listing Multiple Cases

Parameters:

• cmd - API command to be executed
  • cmd=listCases - to list cases using a filter ID
  • cmd=search - to list cases using search criteria

• token
  • token to be used for authentication.

• sFilter

  • this parameter is available only for cmd=listCases
  • the ID of the filter to be used for searching. Filters can be listed using cmd=listFilters

• q

  • this parameter is available only for cmd=search

  • The query term you are searching for can be a string, a case number, or a comma-separated list of case numbers without spaces, e.g. 12,25,556.

    Note: This search parameter works in the same way as the search box on the FogBugz UI, so you can use that to test and debug your search criteria (you can copy-paste any search criteria working on the UI in the q parameter). For more details about how to combine multiple search criteria read our Ultimate FogBugz Search Guide.

  • If q is not present, it returns the cases in your current filter.

  • If the current filter matches a saved or built-in filter, the sFilter is also returned.

• cols 

  • This argument specifies the case columns that you would like to be returned for each case in the list.

  • The parameter should be a comma-separated list of column names:
    (e.g., cols=sTitle,sStatus) 

  • The available columns are listed in the Sample payload as XML output.

  • If you include events, you will also receive all the events for that case. Include latestEvent to get only the latest event.

  • For custom fields and other plugin fields, see Access Custom Fields and Other Plugin Data with the XML API.

  • ix columns can be empty or 0 if they are not set.

  • All valid ix columns (ixPersonClosedBy, for example) will be > 0 if there is a valid person who closed this case.

• max
  • Specifies the maximum number of results you want to be returned.
  • if not set, it defaults to 50.000.
  • the max number of returned results is 100.000. If you set it above 100.000, the API will return error code 30.
  • if you need more results than 100.000, you will need to retrieve them in batches by adjusting your search query q accordingly. For example: if you need all closed cases from last year, try retrieving them in 12 batches, one for each month, and adjust the search criteria accordingly for the 12 different API requests.

Example of listing cases using a saved filter

Step 1 - Retrieve saved filter list

https://yourinstance.fogbugz.com/api.asp?cmd=listFilters&token=yoursecret123456ks9d1234v12r1j

Step 2 - Retrieve the cases and list Title and Status using the saved filter with ID=2

https://yourinstance.fogbugz.com/api.asp?cmd=listCases&sFilter=2&cols=sTitle,sStatus&token=yoursecret123456ks9d1234v12r1j

Back to the top

Listing One Single Case

Parameters:

• cmd - API command to be executed
  • cmd=search - we will search for one case based on its ID

• token
  • token to be used for authentication.
• q
  • passing as search criteria the ixBug id of the case to be listed
• cols
  • passing as parameter the columns of the case that you want to list

Example of listing all events of one case

Listing all event of the case with ID 21:

https://yourinstance.fogbugz.com/api.asp?cmd=search&q=21&cols=events&token=yoursecret123456ks9d1234v12r1j

Back to the top