API Responses

Response Types

class civis.response.Response(json_data, snake_case=True, headers=None)[source]

Custom Civis response object.


The main features of this class are that it maps camelCase to snake_case at the top level of the json object and attaches keys as attributes. Nested object keys are not changed.

json_data : dict | None

This is json_data as it is originally returned to the user without the key names being changed. See Notes. None is used if the original response returned a 204 No Content response.

headers : dict

This is the header for the API call without changing the key names.

calls_remaining : int

Number of API calls remaining before rate limit is reached.

rate_limit : int

Total number of calls per API rate limit period.

class civis.response.PaginatedResponse(path, initial_params, endpoint)[source]

A response object which is an iterator

path : str

Make GET requests to this path.

initial_params : dict

Query params that should be passed along with each request. Note that if initial_params contains the keys page_num or limit, they will be ignored. The given dict is not modified.

endpoint : civis.base.Endpoint

An endpoint used to make API requests.


This response is returned automatically by endpoints which support pagination when the iterator kwarg is specified.


>>> client = civis.APIClient()
>>> queries = client.queries.list(iterator=True)
>>> for query in queries:
...    print(query['id'])
class civis.futures.CivisFuture(poller, poller_args, polling_interval=None, api_key=None, client=None, poll_on_creation=True)[source]

A class for tracking future results.

This class will attempt to subscribe to a Pubnub channel to listen for job completion events. If you don’t have access to Pubnub channels, then it will fallback to polling.

This is a subclass of concurrent.futures.Future from the Python standard library. See: https://docs.python.org/3/library/concurrent.futures.html

poller : func

A function which returns an object that has a state attribute.

poller_args : tuple

The arguments with which to call the poller function.

polling_interval : int or float, optional

The number of seconds between API requests to check whether a result is ready.

api_key : DEPRECATED str, optional

Your Civis API key. If not given, the CIVIS_API_KEY environment variable will be used.

client : civis.APIClient, optional
poll_on_creation : bool, optional

If True (the default), it will poll upon calling result() the first time. If False, it will wait the number of seconds specified in polling_interval from object creation before polling.


This example is provided as a function at query_civis().

>>> client = civis.APIClient()
>>> database_id = client.get_database_id("my_database")
>>> cred_id = client.default_credential
>>> sql = "SELECT 1"
>>> preview_rows = 10
>>> response = client.queries.post(database_id, sql, preview_rows,
>>>                                credential=cred_id)
>>> job_id = response.id
>>> poller = client.queries.get
>>> poller_args = (job_id, ) # (job_id, run_id) if poller requires run_id
>>> polling_interval = 10
>>> future = CivisFuture(poller, poller_args, polling_interval)

Helper Functions

civis.find(object_list, filter_func=None, **kwargs)[source]

Filter civis.response.Response objects.

object_list : iterable

An iterable of arbitrary objects, particularly those with attributes that can be targeted by the filters in kwargs. A major use case is an iterable of civis.response.Response objects.

filter_func : callable, optional

A one-argument function. If specified, kwargs are ignored. An object from the input iterable is kept in the returned list if and only if bool(filter_func(object)) is True.


Key-value pairs for more fine-grained filtering; they cannot be used in conjunction with filter_func. All keys must be strings. For an object from the input iterable to be included in the returned list, all the key`s must be attributes of `object, plus any one of the following conditions for a given key:

  • value is a one-argument function and bool(value(getattr(object, key))) is True
  • value is True
  • getattr(object, key) is equal to value

See also



>>> import civis
>>> client = civis.APIClient()
>>> # creds is a list of civis.response.Response objects
>>> creds = client.credentials.list()
>>> # target_creds contains civis.response.Response objects
>>> # with the attribute 'name' == 'username'
>>> target_creds = find(creds, name='username')
civis.find_one(object_list, filter_func=None, **kwargs)[source]

Return one satisfying civis.response.Response object.

The arguments are the same as those for civis.find(). If more than one object satisfies the filtering criteria, the first one is returned. If no satisfying objects are found, None is returned.

object or None

See also